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Manual Organization 


Chapter 

1 


Welcome 

This manual is intended to introduce you to the Series 200 computer’s BASIC programming 
language and to provide some helpful hints on getting the most utility from it. Although this manual 
assumes that you have had some previous programming experience, you need not have a high skill 
level, nor does your previous experience need to be in BASIC. If you have never programmed a 
computer before, it will probably be more comfortable for you to start with one of the many 
beginner’s text books available from various publishing companies. However, some beginners may 
find that they are able to start in this manual by concentrating on the fundamentals presented in the 
first few chapters. If you are a programming expert or are already familiar with the BASIC language 
of other HP desktop computers, you may start faster by going directly to the BASIC Language 
Reference manual and checking the keywords you normally use. You can always come back to this 
manual when you have extra time to explore the computer’s capabilities, or if you bump into an 
unfamiliar concept. 

Durability is a built-in feature of this easy-to-operate computer, so don’t be afraid to test it. After 
reading each section and trying the examples shown, try your own examples. Experiment. You 
cannot damage the computer by pressing the wrong keys. The worst that can happen is an error 
message will appear. These messages help you learn its language and needs by communicating 
with you. All error codes are listed at the back of this manual. 
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What’s In This Manual? 

No matter what your skill level, it is helpful to understand the contents and organization of this 
manual. First of all, there are some things that it is not. Because it is organized by topics and 
concepts, it is not a good place to find an individual keyword in a hurry. Keywords can be found 
using the index, but even so, they are often imbedded in discussions, contained in more than one 
place, or only partially explained. Also, this is not a good place to find complete syntactical details. 
Program statements are often presented only in the form that applies to the specific concept being 
discussed, even though there may be other forms of the statement that accomplish different 
purposes. If you want to quickly find the complete formal syntax of a keyword, use the BASIC 
Language Reference. It is specifically intended for that purpose. 

This manual contains explanations and programming hints organized topically. A program per¬ 
forms various “sub-tasks” as it completes its overall job. Many of these tasks can, or should be, 
viewed separately to be understood more easily and used more effectively. For example, perhaps 
you have experience in another programming language. You know exactly what a “loop” does, 
but you didn’t find the statement you were looking for in the BASIC Language Reference. In the 
chapter on “Program Flow”, there is a section called “Repetition” which explains the kinds of loops 
available and all the statements needed to create them. The following is an overview of the chapters 
in this manual. 

Chapter 1: Manual Organization 

Chapter 2: Entering, Running, and Storing Programs 

This chapter explains the mechanics of the programming process. It discusses ways to type in a 
program, modify it, run it, print it, make it more readable, and save it on a disc so you can 
continue improving it tomorrow. 

Chapter 3: Program Structure and Flow 

This chapter tells how the computer finds its way around your program and offers ideas on 
getting it to follow the proper path efficiently. 

Chapter 4: Numeric Computation 

This chapter covers mathematical operations and the use of numeric variables. It includes 
discussions on types of variables, expression evaluation, arrays, and methods of managing 
data memory. 

Chapter 5: String Manipulation 

Although string data can be used for any purpose the programmer desires, it is most often 
used for the processing of characters, words, and text. Since words are more pleasant than 
numbers to humans, skillful use of strings can make the input and output of programs much 
more natural to those using the programs. This chapter explains the programming tools 
available for processing string data. 

Chapter 6: User-Defined Functions and Subprograms 

An outstanding feature of this language is its ability to change program contexts and the speed 
with which it can do so. Alternate contexts (or environments) are available as user-defined 
functions or subprograms. These are discussed in this chapter. 
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Chapter 7: Data Storage and Retrieval 

This chapter shows many of the alternatives available for storing the data that is intended as 
program input or created as program output. Topics range from convenient ways to define 
constants to a discussion of the computer’s unified mass storage system. 

Chapter 8: Using a Printer 

This chapter tells how to connect and use an external printer. Also covered are the formatting 
techniques (useful on both printer and CRT) to create organized, highly-readable printouts. 

Chapter 9: Using the Real-Time Clock 

An accurate real-time clock is available with timing resolution to the hundredth of a second 
and a range of years. Its capabilities are covered in this chapter. 

Chapter 10: Communicating with the Operator 

It is very fustrating for operator and programmer alike when the operator cannot figure out 
what is expected next, or the program crashes every time a wrong key is pressed. The chapter 
presents some programming techniques that help ease the interaction between the computer 
and a human operator. 

Chapter 11: Error Handling 

This chapter discusses techniques for intercepting (or trapping) errors that might occur while a 
program is running. Many errors can be dealt with easily by a programmer. Error trapping 
keeps the program running and provides valuable assistance to the computer operator. 

Chapter 12: Program Debugging 

We all wish that every program would run perfectly the first time and every time. Unfortunate¬ 
ly, there is little evidence in real life to support that fantasy. The next best thing is to get the 
computer to do most of the debugging work for you. This chapter explains the powerful 
debugging features available on the computer. 

Chapter 13: Efficient Use of the Computer’s Resources 

Which takes longer, calculating a square root or raising a number to the .5 power? Does a 
program run faster if the variable names are shorter? If you have a time-critical or memory- 
critical application, you will be interested in these answers and others provided in this chapter. 

Chapter 14: Graphics 

Another of the computer’s significant features is its fast, precise graphics capability. Graphics is 
very useful for generating results in a human-compatible form. This chapter introduces the 
techniques of programming with graphics. 

Chapter 15: Translating Programs 

This chapter helps the user who is transporting programs from previous versions of BASIC. It 
discusses changes and enhancements. 






4 Manual Organization 


This is a manual of programming techniques, helpful hints, and explanations of capabilities. It is not 
a rigorous derivation of the BASIC language. Any statements appropriate to the topic being 
discussed are included in each chapter, whether they have been previously introduced or not. 
Since most users will not read this manual from cover to cover anyway, the approach chosen 
should not present any significant problems. In those cases when you have difficulty getting the 
meaning of certain items from context, consult the Index to find additional information. 
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Printing History 


New editions of this manual will incorporate all material updated since the previous edition. Update 
packages may be issued between editions and contain replacement and additional pages to be 
merged into the manual by the user. Each updated page will be indicated by a revision date at the 
bottom of the page. A vertical bar in the margin indicates the changes on each page. Note that pages 
which are rearranged due to changes on a previous page are not considered revised. 

The manual printing date and part number indicate its current edition. The printing date changes 
when a new edition is printed. (Minor corrections and updates which are incorporated at reprint do 
not cause the date to change.) The manual part number changes when extensive technical changes 
are incorporated. 

May 1984...First Edition 


Warranty Statement 

Hewlett-Packard products are warranted against defects in materials and workmanship. For Hewlett-Packard Fort Collins 
Systems Division products sold in the U.S.A. and Canada, this warranty applies for ninety (90) days from the date of delivery.* 
Hewlett-Packard will, at its option, repair or replace equipment which proves to be defective during the warranty period. This 
warranty includes labor, parts, and surface travel costs, if any. Equipment returned to Hewlett-Packard for repair must be 
shipped freight prepaid. Repairs necessitated by misuse of the equipment, or by hardware, software, or interfacing not 
provided by Hewlett-Packard are not covered by this warranty. 

HP warrants that its software and firmware designated by HP for use with a CPU will execute its programming instructions 
when properly installed on that CPU. HP does not warrant that the operation of the CPU, software, or firmware will be uninter¬ 
rupted or error free. 

HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett- 
Packard shall not be liable for errors contained herein or for incidental or consequential damages in connection with the 
furnishing, performance or use of this material. 

* For other countries, contact your local Sales and Support Office to determine warranty terms. 
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Entering, Running, and 
Storing Programs 


Chapter 


Introduction 

The first thing a programmer needs to know is how to get a program into the computer. If your 
background is punched cards and batch jobs, you will be delighted to discover how easy program 
writing is on Series 200 computers. If you have experience on other HP desktops, you should find 
the computer’s programming procedures familiar, with some improvements. Whatever your start¬ 
ing point, it makes sense to learn the mechanics of program writing before you become absorbed in 
a study of all the available program statements. 


Some BASIC Vocabulary 


What Is a Program? 

A main program is a list of program lines, with an END statement on the last line. A program line 
contains at least a line number followed by a statement 1 . A statement is a keyword (sometimes 
optional) followed by any parameters, lists, specifiers, and secondary keywords that are 
allowed with that keyword and fit in the program line. The maximum length of a program line is 
256 characters. When entering programs from the keyboard, the maximum length is reduced to 
two CRT lines. A keyword is a group of uppercase characters that is understood by the 
computer’s language system to represent some predefined action. 

The computer also allows subprograms to be appended to a main program. Subprograms are 
also lists of program lines, but they have special requirements for their first and last lines. 
Subprograms are a useful programming tool, but the computer is capable of running just fine 
without them. Therefore, most of the concepts in this manual are presented using examples in a 
main program context. Subprograms are covered in depth in “User-Defined Functions and 
Subprograms” Chapter. 


1 A line number may be optionally followed by a line label. A line label is a name that is placed after the line number and is terminated by a 
colon. Chapter 3 tells more about labels. 
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What Is a Command? 

This manual makes frequent reference to “statements” and “commands”. As previously men¬ 
tioned, a statement is a keyword followed by any other elements that are appropriate for that 
keyword. If a statement is placed after a line number and entered, it becomes a program line. If a 
statement is typed without a line number and executed, it is called a command. There are some 
commands that cannot be stored as program lines, such as those using DEL and SCRATCH. There 
are also statements that can’t be executed as commands, such as those using DIM and RETURN. 
However, many statements are both programmable and executable, such as those using PRINT 
and CALL. 

When a keyword is described, the most descriptive term (statement, command, or function) is used 
and any restrictions are noted in the text. Since these terms are not necessarily mutually exclusive, 
read more than just the one term to determine the legal uses of a keyword. For example, the use of 
the term “statement” does not imply that a certain keyword is not keyboard executable; but the 
phrase “cannot be executed as a command” clearly indicates that a keyword can only be used in a 
program line. 

Enter or Execute 

Entering a program line means that you type a line number followed by a valid statement and then 
press one of these keys: ( RETURN ) . (ENTER) , ( EXECUTE ) or (IXECl . The line is stored p memory as 
part of a program. The line performs no function until you run the program. 

Executing a command means that you type a statement (no line number) and press one of the keys 
listed above. The command is executed immediately. It is not stored in a program. 

Depending on the keyboard, you have at least one of the keys listed. In most cases it does not 
matt er which k ey you use. (In some Edit modes such as FIND there is a difference between ( ENTER) 
and ( EXECUTE ) .) 

( KEYS) 

Throughout the BASIC manuals you will see a word, letter or symbol enclosed in a box. This 
indicates an actual key on the keyboard, or a function key shown on the menu on the display. 

There are several different keyboards for the Series 200 computers. Each keyboard has slightly 
different key labels. (The BASIC User’s Guide describes all keyboards in detail,) Within this manual 
the keys are listed once the first time they are used in a topic. Thereafter, only one of the keys is 
used. If you have any confusion over which key to use, refer to the BASIC User’s Guide which 
includes a table of keys. 
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Using EDIT Mode 

It is possible to enter a program by typing entir e prog ram lines (line number and statement) on the 
normal input line of the CRT and pressing the f ENTER) or [ RETURN ) key. There are some disadvan¬ 
tages to this method. First, it forces you to type in the line number (which means you have to 
remember what line number needs to be supplied). Second, the program lines disappear after they 
are entered, so it is difficult to keep track of where you are in the program and what the lines above 
are doing. Third, there is no way to review the program except the LIST command. Listing to a 
printer gives a readable copy of the program, but is slow and paper-consuming during program 
development. A program listed to the CRT goes by so fast that you won’t be able to read anything 
but the end. Listing program portions to the CRT requires you to remember the line numbers of 
every segment you want to see. The solution to all these problems is the EDIT mode. 

Getting Into EDIT Mode 

To get into EDIT mode, either press the ( EDIT ) key or type the word EDIT, then press ( RETURN ) 
or ( EXECUTE ) . As a result, the format of the CRT display is transformed as shown in the following 
diagram. 


- Previous Program Lines (if any) 

► Current Program Line (2 CRT lines) 

j 

} System Message Line (if needed) 

• Following Program Lines (if any) 

• Softkey Labels 


In this mode, you can view several lines before and after the line you are editing. The system 
supplies the line number for the current line and program portions can be viewed by simple 
scrolling. 

The EDIT command allows two parameters. The first is a line identifier and the second is the 
increment between line numbers. For example: 

EDIT 1flQ #20 

This command tells the computer to place the program on the CRT so that line 140 is in the 
current-line position. Also, any lines that are added to the program get a line number 20 greater 
than the previous line. 
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If the increment parameter is not specified, the computer assumes a value of 10. For example: 
EDIT 1000 

This command tells the computer to place the program on the CRT so that line 1000 is in the 
current-line position, and added lines get a line number 10 greater than the previous line. 

When the line identifier is not supplied, the computer has some interesting ways of assuming a line 
number. If this is the first EDIT after a power-up, SCRATCH, SCRATCH A, SCRATCH BIN or 
LOAD, the assumed line number is 10. If EDIT is performed immediately after a program has 
paused because of an error, the number of the line that generated the error is assumed. At any 
other time, EDIT assumes the number of the line that was being edited the last time you were in 
EDIT mode. 

The line identifier also can be a line label. This makes it very easy to find a specific program segment 
without needing to remember its line number. For example, assume that you want to edit a sorting 
routine that begins with a line labeled “Go_sort”. Simply execute: 

EDIT G0_S0RT 

The line labeled “Go_sort” is placed in the current-line position and the next several lines of the 
routine are displayed below it. 

The EDIT command is not programmable and cannot be used while a program is running. 

Editing the Current Line 

The BASIC User’s Guide explains the keyboards and its use for typing and editing on the input line. 
All of these normal editing features are available in EDIT mode, plus some additional actions 
specific to programming. The extra EDIT mode features are explained in subsequent sections. 

Entering Program Lines 

Program lines are entered by typing them after the line number and pressing ( ENTER) , ( RETURN } or 
t EXECUTE ) . Before storing the line, the computer checks for syntax errors and converts letter case to 
the required form for names and keywords. 

Although the computer supplies a line number automatically, you are not forced to use that number 
if you don’t want to. To change the line number, simply back up the cursor and type in the line 
number you want to use. This can be done to existing lines as a way of copying them to another 
part of the program. When you change a line number, the program is moved on the CRT so that 
the line just stored is one line above the current-line position. In other words, when you move a line 
to a new location, the new location is displayed. 

Here are some points to keep in mind when changing the line numbers supplied by the computer. 
Changing the line number of an existing line causes a copy operation, not a move. The line still 
exists in its original location. Existing lines are replaced by any line entered with their same line 
number. Be careful that you don’t accidentally replace a line because of a typing mistake in the line 
number. 
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Syntax Checking 

Syntax is a term used to describe the elements that compose a line and their order. Immediate 
syntax checking is one big advantage of writing programs in HP BASIC instead of turning in a batch 
of punched cards. A great many programming errors can be detected at program entry time, which 
increases the chances of having a program run properly and cuts down debugging time. If the 
syntax of the line is proper, the line is stored, and the next line number appears in front of the 
cursor. 

If the system detects an error in the input line, it displays an error message immediately below the 
line and places the cursor at the location it blames for the error. Keep in mind that there is an 
endless variety of human mistakes that might occur and the computer is acting on erroneous input. 
As a result, you might not always agree with its diagnosis of the exact error or the error’s location. 
However, an error message is proof that something needs to be fixed. There is a complete list of 
error messages and their meanings in the last chapter of this manual. 

Uppercase or Lowercase? 

Program entry is simplified by the computer’s ability to recognize the uppercase and lowercase 
requirements for most elements in a statement. An entire statement can be typed using all upper¬ 
case or all lowercase letters. If the statement’s syntax is otherwise correct and there are no keyword 
conflicts, the computer places all keywords in uppercase and all variable names i n lowe rcase with 
an uppercase first letter. In other words, you don’t usually have to bother with the ( SHIFT ) key when 
you enter a line, because the computer knows what the line is supposed to look like. If there is a 
keyword conflict, an error occurs. A keyword conflict occurs when the letters of a keyword are used 
as an identifier (variable name, line label, or subprogram name). When this happens, simply 
change the case of at least one letter in the identifier name and enter the line again. A word 
containing a mixture of uppercase and lowercase letters is assumed to be an identifier. 

The computer’s assumptions about the appearance of a line won’t cause any problems if your line 
has the proper syntax. However, if you are guessing at a keyword or syntax, don’t assume that you 
got the line right just because the computer stored it. Take a close look at what was stored. If the 
computer put lowercase letters in something that you thought was a keyword, then it wasn’t really a 
keyword. That misspelled “keyword” was perceived as a subprogram call or a variable name by 
the computer. 

Inserting Lines 

Lines can be easily inserted into a program. As an example, assume that you want to insert some 
lines between line 90 and line 100 in your program. Place line 100 in the current-line position and 
press the insert line key. The program display “opens” and a new line number appears between 
line 90 and line 100. Type and store the inserted lines in the normal manner. Appropriate line 
numbers will appear automatically. The insert mode can be cancelled by pressing the insert line key 
again or by performing an operation that causes a new current line to appear (such as scrolling). 

While inserting lines, the computer maintains the established interval between line numbers, if 
possible. If the interval between lines in the preceding example was 5, the first line number 
appearing would be 95. When the normal interval between lines can no longer be maintained, an 
interval of 1 is used. Thus, after line 95 is stored, the next line number supplied is 96. When there 
are no line numbers available between the current line and the next line, enough of the program 
below the current line is renumbered to allow the insert operation to continue. In the example, this 
would happen after line 99 is stored. The original line 100 is renumbered to 101 and the number 
100 appears in the current line. 
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Deleting and Recalling Lines 

Lines can be deleted one at a time or in blocks. The delete line key is used to delete the current line. 
If delete li ne is pressed by mistake, the line can be recovered by pressing ( RECALL 1 . then (ENTER] or 
t RETURN ] . The computer has a recall buffer that holds the last several lines entered, deleted, or 
executed. 

The DEL command can also be used to delete lines. When the keyword DEL is followed by a single 
line identifier, only a single line is deleted. The line identifier can be a line number or a line label. A 
combination of an EDIT command and a press of the delete line key produces the same results, but 
has some advantages. There is a typing aid key to start the command, you can see the line before 
you delete it, and the delete line key saves the line in the recall buffer (the DEL command does 
not). Therefore, DEL is more useful for deleting blocks of lines. 

Blocks of program lines can be deleted by using two line identifiers in the DEL command. The first 
number or label identifies the start of the block to be deleted, and the second number or label 
identifies the end of the block to be deleted. The line identifiers must appear in the same order they 
do in the program. Here are some examples. 

DEL 100 #200 Deletes lines 100 thru 200, inclusive. 

DEL Bloc K 2 #32766 Deletes all the lines from the one labeled ‘ ‘Block2’ ’ to the end of the 

program. 

DEL 2 5 0 # 10 Does nothing except generate an error. 

If you have subprograms or user-defined functions in your program, they can only be deleted in 
certain ways. Primarily, the SUB or DEF FN statement cannot be deleted without deleting the entire 
subprogram or function. This is explained fully in the “User-defined Functions and Subprograms” 
chapter. A CSUB line can be deleted, and doing so removes the entire subprogram. 

The DEL command is not programmable and cannot be used while a program is running. 

Renumbering a Program 

After an editing session with many deletes and inserts, the appearance of your program can be 
improved by renumbering. This also helps make room for long inserts. Renumbering is done by the 
REN command. The starting line number, the interval between lines and the range can be speci¬ 
fied. For example: 

REN 100#5 IN 1#500 

This command renumbers current lines 1 thru 500, using 100 for the first line number and an 
increment of 5. If the increment (second parameter) is not specified, 10 is assumed. If a range is not 
specified, the entire program is renumbered. For example: 

REN 1000 

This command renumbers the entire program, using 1000 for the first line number and an incre¬ 
ment of 10. When no parameters are specified (REN), 10 is assumed for the first line number and 
the increment, and the entire program is renumbered. 
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Listing a Program 

All or part of your program can be displayed or printed by executing a LIST statement. The LIST 
statement allows parameters that specify both the range of lines to be listed and the device to which 
the listing should be sent. If the keyword LIST is executed without any parameters, the assumed 
action is to list the entire program on the system printer. The default system printer after a power-on 
or SCRATCH A is the CRT. (The system printer is defined by the PRINTER IS statement.) 

Starting and ending line numbers can be specified in the LIST statement. The line identifiers can be 
labels. For example: 

LIST 100*200 Lists lines 100 thru 200, inclusive. 

LIST 1850 Lists the last portion of the program, from line 1850 to the end. 

LIST Rocket Lists the program from the line labeled “Rocket” to the end. 

Directing the listing to a device other than the CRT is easy, but involves concepts that have not 
been introduced yet. If you want a listing on an external printer and you don’t understand the brief 
examples here, refer to the beginning of the “Using a Printer” chapter for an explanation of device 
selectors. One way to get a listing on an external printer is to specify a different system printer. This 
is done with the PRINTER IS statement described in the “Using a Printer” chapter. However, it is 
often desirable to keep the CRT as system printer and still get program listings on an external 
printer. This is done by specifying the printer in the LIST statement. For example: 

LIST #701 

This statement sends the entire program listing to an HP-IB printer (address 01) without changing 
the system printer selection. When both the printer and the line range are specified, the printer 
number is specified first and terminated with a semicolon. The following example lists lines 200 thru 
500 on the device serviced by interface select code 12. 

LIST #125200*500 

Using Comments 

When first learning how to program, most people view the use of comments, long variable names, 
descriptive printouts, and other documentation tools as merely extra typing that isn’t really neces¬ 
sary in their short programs. As time passes, old programs are expanded, new programs are written, 
and more people use the available software. Eventually, software support activities become neces¬ 
sary. Some obscure bug is found or some exciting enhancement is requested. The programmer 
picks up a copy of a program written a year ago and can’t begin to remember what “XI” was or 
why you would ever want to divide it by “X2”. Program documentation can make the difference 
between a supportable tool that adapts to the needs of the users and a support nightmare that 
never really does exactly what the current user wants. Keep in mind that the local software support 
person just might be you. 
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The BASIC language on Series 200 computers makes it easy to write self-documenting program^. 
In addition to BASIC’s standard REM (remark) capability, its primary documentation features are 
line labels, 15-character names, and end-of-line comments. Although this section deals primarily 
with commenting methods, all of these features work together to make a readable program. The 
following example shows two versions of the same program. The first version is uncommented and 
uses “traditional” BASIC variable names. The second version uses the features of HP’s BASIC 
language to make the program more easily understood. Which version would you rather work 
with? 


100 PRINTER IS 1 

110 A= . 03 

120 B =.02 

130 X = 0 

140 Y=0 

150 C = A + B 

1B0 PRINT " Item Total Total" 

170 PRINT " Price Tax Cost" 

180 PRINT "- 

190 P=0 

200 INPUT "Input item p ric e" >P 

210 IF P<0 THEN 290 

220 D = P*C 

230 E = P + D 

240 X=X+D 

250 Y=Y+E 

2 G 0 DIS P "Tax ="5 D ?"11 e m cost = " ? E 
270 PRINT P *Y\ >Y 
280 GOTO 190 
290 END 


100 
110 
120 
130 
140 
150 
1 GO 
170 
180 
190 
200 
210 
220 
230 
240 
250 
2G0 
270 
280 
290 
300 
310 
320 
330 
340 
350 
3G0 
370 
380 
390 
400 
410 
420 
430 
440 
450 


This program computes the sales tax for 
a list of prices* Item prices are input 
individually* The tax and total cost for 
each item are displayed* The running 
totals for tax and cost are printed on 
the CRT* Modify line 220 to change the 
the system printer* 

Sales tax rates are assigned on lines 230 
and 240* The rates used in this version 
of the program were in effect 1/1/81* 


PRINTER IS 1 ! 

State_tax=*03 ! 

Cit y _ t a x = *02 
! 

Total_tax=0 ! 

Total_cost=0 

Tax_rate=State_tax+City_tax 

! 

PRINT " Item Total 

PRINT " Price Tax 

PRINT "- 


Use CRT for printout 
Local tax rates 


Initialize variables 


Print column headers 
Total" 

Cost" 


Get_price: ! Start of main loop 

P ric e = 0 ! Don't change totals if no entry 

INPUT "Input item price"»Price 

IF Price<0 THEN Done ! Negative entry stops program 

Tax=Price*Tax_rate 

Item_cost=Price+Tax 

Total_tax=Total_tax+Tax ! Accumulate totals 

Total_cost=Total_cost+Item_cost 
DISP "Tax =" !Tax I" Item cost =" !Item_cost 
PRINT Price>Total_tax»Total_cost 

GOTO Get_price ! Repeat loop for next item 

Done: END 
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There are two methods for including comments in your programs. The use of an exclamation point 
is demonstrated in the second example program. The exclamation point marks the boundary 
between an executable statement and comment text. There does not have to be an executable 
statement on a line containing a comment. Therefore, the exclamation point can be used to 
introduce a line of comments, to add comments to a statement, or simply to create a “blank” line to 
separate program segments. Exclamation points may be indented as necessary to help keep the 
comments neat. 

The REM statement can also be used for comments. The exclamation point is neater and more 
flexible, but the REM statement provides compatibility with other BASIC languages. The REM 
keyword must be the first entry after the line identifier and must be followed by at least one blank. 
Here are some examples of proper and improper REM statements. 


RIGHT 


WRONG 


10 REM Check Book Balance 
40 StartZ: REM Subtotal loop 


20 REMinitialize array 
50 X=PI*R'Z REM Area of circle 


Each programmer has an individual style in the use of comments. Therefore, the following is not a 
list of rules. It is simply some suggestions on the effective use of comments. 

• Include a heading on programs that tells the purpose of the program. Why was the program 
written, what does it do, and who would probably be using it? 

• Give any helpful support information, such as the author of the program, the revision date, 
where to call or write for help, and instructions for any modifications that might be made by a 
normal user. 

• Identify all significant variables, especially global variables. A descriptive variable name may do 
the job, or a more detailed explanation may be needed. 

• Describe any input or output devices that are required for the proper running of the program. 
This may even include an explanation of how to modify the program to accommodate alter¬ 
nate devices (when such changes are reasonable). 

• Make major blocks and entry points visible. Many tools are available for this, including descrip¬ 
tive labels, indenting, spacing, and comments describing program flow. 

• Use comments freely to describe the action of complex lines, equations, fancy manipulations, 
and “low-level” operations like CONTROL statements and escape code sequences. These 
heavily coded operations can be very important to the computer and very mysterious to the 
human trying to read the program. 
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Getting Out of EDIT Mode 

There are many ways to terminate the EDIT mode. Your choice depends upon what you want to 
do next. If you simply want t o return the CRT t o its “normal” m ode (input line on the bottom and 
printout area above), press (PAUSE] , ( CLR SCR ] or ( Clear display ) . Either of these keys terminates 
EDIT mode and returns the screen to the normal format. 

Another way to leave EDIT mode is to proceed with another operation. The key choices in this case 
are (RESET) , ( RUN ) . ( STEP ) . and ( CONTINUE ] . All of these keys t ermina te EDIT mode and perform 
their normal function. A detailed list of the items affected by ( RESET) is contained in the “Useful 
Tables” chapter at the back of the BASIC Language Reference. The ( RUN ) key starts normal 
progra m execution. This is described in the “Running a Program” section of this chapter. The 
( STEP ) key starts single-step program execution, as described in the “Program Debugging” 
chapter. 

CONTINUE is not always a valid way to leave EDIT mode. If you paused a program and used EDIT 
mode only as a means of looking at various program segments, ( CONTINUE ) may be pressed to 
resume program execution. However, if any program lines are changed while in EDIT mode, the 
program moves from the paused state into the stopped state. In that case, CONTINUE is not a valid 
operation and results in an error. This is covered in the next section, “Running a Program” 

EDIT mode is also terminated by a GET or LOAD operation or by an operation that uses the CRT 
(for example: CAT). 
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Running a Program 

The normal running of a program is started by the ( RUN ) key o r the R UN command . Pressing the 
( RUN ) key is equivalent to typing RUN and pressing ( EXECUTE ) , (ENTER) or ( RETURN ) . This tells the 
computer to go through a prerun phase and then begin normal program execution with the lowest 
numbered line in the main program. The RUN command can also be followed by a line identifier 
that lets you specify where the program execution is to begin. 

Prerun 

There are three primary reasons for the prerun. The first purpose is to reserve sufficient memory for 
all the variables in the program (except those that are ALLOCATEd). This includes all variables in 
COM statements, those declared in DIM, REAL, and INTEGER statements, and all implicitly 
declared variables. The “Number Computation” chapter explains the declaration of numeric vari¬ 
ables, and the “String Manipulation” chapter covers the dimensioning of string variables. 

The second purpose is to locate all the context boundaries. These are defined by the END, SUB, 
SUBEND, DEF FN, and FNEND statements. 

The third purpose of the prerun is to detect errors that involve interaction between lines. The 
previous section explained that the computer checks for syntax errors before it stores a program 
line. Although this is true, there are some errors that can’t be detected by looking at a single line. 
For example, a program line that uses properly placed subscripts can appear to be correct when it is 
stored. However, if that line references three dimensions in an array that had previously been 
declared to have only two dimensions, it is in error. To detect an error of that kind, the computer 
needs to “look at” the entire program to see all the dimension statements as well as the variables 
used in each line. Some other examples of this kind of error are specifying a ON...GOTO to a line 
that does not exist or improper matching of statements like FOR...NEXT and IF...END IF. 

Normal Program Execution 

Program execution is not a method for destroying programs (although there are some reported 
cases of programmers having an urge to kill). The term execution is used to describe the process 
used by the computer while it is completing the tasks described in its program. The process of 
program execution is summarized below. 

1. Determine which program line is to be acted on next. 

2. Identify the statement that follows the line number and label (if any) on that line. 

3. If the statement has a run-time action, perform the action described in the statement. 

4. Repeat steps 1 thru 4 until an END, STOP, or PAUSE statement is executed. 

The continuing process of determining which line is to be executed next is discussed in detail in the 
next chapter, “Program Structure and Flow”. The RUN comm and de termines which line is acted 
on first. Executing RUN with no parameters, or pressing the ( RUN ) key, causes the execution 
process to begin at the first (lowest-numbered) line of the main program. Execution can be started 
anywhere in the main program by using the RUN command with a line identifier. For example: 


RUN 220 
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This command causes execution to begin at line 220, if there is such a line. If there is no line 220 in 
the main program, execution begins with the line whose number is closest to and greater than 220. 
The line identifier can also be a label. For example: 

RUN Spot-run 

This command causes execution to begin with the line labeled “Spot-run”. If there is no such label, 
an error results. 

Note that the prerun phase is always the same, whether the actual execution begins at the program 
start or somewhere in the middle. Also, if a starting line is specified, that line must be in the main 
program. An error 3 results if you attempt to start a program in a user-defined function or subprog¬ 
ram. Even if the starting point is correctly specified, be alert to the effects of starting a program in the 
middle. Skipping over a section of the program may result in null values for some of the variables. 
Although it is legal to start in the middle of a subroutine, an error is generated when the RETURN 
statement is executed. 

Non-Executed Statements 

In the preceding summary of normal execution, step 3 mentioned that only statements with 
run-time actions are executed. The term run-time refers to the state that exists after the prerun, 
when the computer is actually performing the actions described in the program. Some statements 
are not executed in the course of normal program flow, but are merely “looked at” and then 
bypassed. The following is a list of some statements that do not cause an action as a result of 
run-time execution. 

• Comments and REM statements. These never cause an action. 

• Variable declarations; COM, DIM, REAL, and INTEGER. These are executed during prerun 
and skipped over at run-time. The OPTION BASE statement is part of the declaring process. 

• DATA statements. These are accessed by the READ statement, not executed. 

• SUB and DEF FN statements. These are used during prerun to establish the program structure 
and are skipped over at run-time. 

• Structuring statements, such as LOOP, END LOOP, ELSE, END IF, etc. These are matched 
and checked for proper nesting at prerun. 

Live Keyboard 

When a program is running, the keyboard is still active. Commands can be executed, variables can 
be inspected and changed, and the state of the computer can be changed. The term live keyboard 
is used when talking about commands that are executed during a running program. One of the 
principal uses for live keyboard commands is the troubleshooting and debugging of programs in the 
development stage. This application is covered in the “Program Debugging” chapter. The discus¬ 
sions presented here are intended to demonstrate the various machine states (running, paused, and 
stopped). 
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Pausing and Stopping 

If the operator does not intervene, a program will run until it reaches an END, STOP, or PAUSE 
statement, or until it pauses to input some data o r report an e rror. If you wish to pause or stop a 
program before its normal completion , the (PAUSE) , ( STOP ) , or f RESET ) key s can be used. Here is a 
summary of the action of these keys. ( (CLR I/O) has an action very similar to (PAUSE) if the computer is 
executing an I/O statement.) 

• (RESET) — This stops the p rogram immediately, aborting any I/O operations and resetting 
any interface cards. (RESET) does not affect the printout area of the CRT, program or variable 
memory, tabs, or the recall buffer. CONTINUE is not allowed after a RESET. 

• ( STOP ) — This stops the program after the computer finishes executing the current line. STOP 
does not affect the interfaces, the CRT, program memory, the values of variables, tabs, or the 
recall buffer. STOP returns the program to the main context. CONTINUE is not allowed after a 
STOP. 

• (PAUSE) — This pauses program execution after the computer finishes the current line and any 
I/O operations in progress. PAUSE leaves all nec essary int ernal informati on intact, so that 
program execution can be resumed again with the ( CONTINUE ) key. Pressing ( CONTINUE ) after a 
PAUSE causes program execution to resume in a normal manner from the place where it was 
paused. 

• (CLR I/O) — This aborts any I/O statement in progress and pauses the program. The program 
counter is returned to the beginning of the aborted I/O statement, so that CONTINUE causes 
the program to resume with that same statement. This is useful when the computer is “hung” 
trying to output to a device that is down, or for pausing a program that is executing an INPUT 
statement. 

On an HP 46020A keyboard, STOP is fSHiFD fST0P~) , PAUSE is ( STOP ) , CLR I/O is (BREAK) . 

The current state of the computer is indicated in the lower right-hand comer of the CRT. The 
character in this corner is referred to as the “run light”. The following table shows the various 
indications of the run light and their meaning. 


Indicator 

Computer State 

(blank) 

Program stopped; CONTINUE not allowed 

i 

Program running 

- 

Program paused; may be continued 

10 

Program paused, but a TRANSFER is still active 

? 

Computer is waiting for an input from the keyboard 

# 

Computer is executing a command from the keyboard 
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For Example 

To demonstrate some of the interaction between a program and the keyboard, enter the following 
simple program. 

10 DISP "NEXT COMMAND?" 

20 X = 0 

30 PRINT Xi 
40 X=X+1 

50 WAIT .1 

60 GOTO 30 

70 END 

1. After you have entered the program, press ( RUN ) and observe the CRT. Notice that the 
DISP message appears in the display line, the printout area fills with a sequence of numbers, 
and the run light indicates that a program is running. 

2. Press (PAUSE) . The printout of numbers stops, and all the data on the CRT remains un¬ 
changed. The run light now indicates that the program is paused and can be continued. The 
program line that appears at the bottom of the CRT is the next line that will be executed 
when program execution resumes. 

3. Press ( STEP ) a number of times. The program is executed one line at a time, as indicated by 
the lines changing at the bottom of the CRT. Not ice tha t the program is still paused and 
continuable after each press of the ( STEP ) key. The ( STEP ) key can be a great help when you 
are trying to find certain kinds of problems. Chapter 12 “Program Debugging” gives the 
details of this and other debugging tools. 

4. Press ( CONTINUE ) . The printout on the CRT resumes with the next number in the sequence. 
The run light again indicates that a program is running. 

5. Press ( STOP ) . The printout of numbers stops, and all the data on the CRT remains un¬ 
changed. However, the run light is off, indicating a stopped condition. 

6. Press ( CONTINUE ) . An error results. A stopped program cannot be continued. 

7. Press ( RUN ) . The program runs again, but the number sequence has restarted from the 
beginning, not from the next number in the sequence. RUN causes the program to restart, 
not resume. 

8. Type X = 1 and press ( EXECUTE ) or ( RETURN ) . Notice that the numbers being printed start 
over with “1”. The live keyboard was used to change the value of “X”, and the program 
used the new value from the keyboard. 

9. Press ( RESET ) . The program stops and the data remains in the printout area, but the display 
line is cleared and the message BASIC Reset appears at the bottom of the CRT. 
Although t he clea ring of the display line seems like a minor effect, it indicates an impor¬ 
tant point (RESET) and STOP have different effects on interfaces and peripheral devices. This 
aspect of (RESET) is summarized in the RESET Tables in the back of the BASIC Language 
Reference and is discussed fully in the BASIC Interfacing Techniques manual. 

10. Press ( RUN ) , then type WAIT 5 and press execute. Notice that the run light changes to 
indicate that a keyboard command is being executed and the printout is delayed for five 
seconds while the live keyboard command is processed. Actually, the run light changed 
when the X = 1 command was executed in step 8, but it happened so fast that you didn’t see 
it. 

































Entering, Running, and Storage Programs 19 


11. Press (PAUSE) , then type EDIT and press ( EXECUTE ) or ( RETURN ) . The display on the CRT 
changes to show the program. The line you were editing last appears in the current-line 
position. Notice that the run light is still visible in the lower right-hand comer and it indicates 
that the program is paused. 

12. Press ( CONTINUE ) . The CRT returns to normal mode, and the printout of numbers continues in 
sequence. However, the previous data on the display was lost when the CRT was used for 
EDIT mode. 

13. Press (PAUSE) , then type EDIT 50 and press ( EXECUTE ) or ( RETURN ) . The CRT changes to 
EDIT mode, and the program appears again. This time, line 50 is in the current-line position. 
Notice that the ru n lig ht indicat es that the program is paused. Change line 50 to W AIT .2 
and press (ENTER) or ( RETURN ) . The new line 50 is entered, but the run light goes out. 
Changing the program caused it to move from the paused state to the stopped state. 

14. Press ( CONTINUE ) . An error results. As mentioned earlier, a program can be viewed while it is 
paused, but it cannot be changed. Once any program line has been changed, the program is 
no longer paused, and CONTINUE is not allowed. 

This simple demonstration covers most of the highlights of live keyboard, program states, and the 
run light. The “waiting for input” indication can be seen when using the INPUT and LINPUT 
statements described in Chapter 10, “Communicating with the Operator”. The “paused with 
TRANSFER completing” indication is not described in this manual. It is a special state that results 
from the use of overlapped I/O and is discussed in the BASIC Interfacing Techniques manual. 
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Wholesale Program Editing 

There are some commands which make is easy to do large amounts of program editing very 
quickly. Among these are commands to move blocks of text, copy blocks of text, replace occurr¬ 
ences of one string with another string, find occurrences of a string, cross-reference the program, 
selectively load and delete subprograms, and more. A detailed explanation of these commands 
follows. Some commands require the PDEV or XREF extensions. 

Moving Program Segments 

Often during program development, you enter a section of code that performs some function, 
thinking that this function will only be needed in that one place. Sure enough, a short time later you 
find that you need it here and here, too. It becomes obvious that the section of code would be 
much better as a subprogram. But how on earth do you move those thirty-five lines of code? You 
certainly don’t want to retype the whole thing. The non-programmable MOVELINES command is 
made for just this type of problem. What you need to do is: 

1. Go to the end of the program (after everything else). 

2. Enter the subprogram header (because you can’t enter a SUB or DEF FN statement if there 
are other statements following it). 

3. Move the text from its old position to a line number greater than the line number of the SUB 
or DEF FN statement you entered in Step 2. 

4. Terminate the new subprogram with a SUBEND or FNEND. 

5. Go back to the place where the code came from, and enter a line which invokes the new 
subprogram. 

Another situation in which MOVELINES is very useful is in a large program which is developed 
over a period of time. You eventually come to the point where it would be nice to have the 
logically-connected subprograms together in their respective areas of the program. A typical exam¬ 
ple follows. 

Your program has these main functions: 

• Load the data 

• Edit the data 

• Print a report 

• Plot a graph 

• Store the data 

The Editing, Printing, and Plotting options may each have options of their own. You’d like the Load 
subprogram to be followed by all the Edit subprograms, followed by all the Printing subprograms, 
etc. The MOVELINES command is a tremendous aid in doing this; however, there is one 
restriction: you cannot move a subprogram to a point where there would be lines of code after it. 
That is, you cannot move a subprogram to a line number which is less than or equal to the largest 
line number. Nevertheless, the same thing is accomplished by moving other things to the end of the 
program. Say you have subprograms A, C, D, and B in that order, and you want them in A, B, C, D 
order. You’d like to move subprogram B to a position between A and C. You can’t do this. But you 
can do something else which amounts to the same thing: move both C and D to a point after B. 
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Note that when dealing with entire subprograms with either MOVELINES or COPYLINES (discus¬ 
sed next), any comments which occur after the SUBEND or FNEND must be moved/copied also. 

This is a good way to insure that the many utility subprograms used by large programs can be found 
in an extensive listing: put them in alphabetical order. 

Copying Program Segments 

The non-programmable COPYLINES command is similar to the MOVELINES command, except it 
leaves the code in the old location also. This is desirable when you want a section of code that is 
very similar, but not identical to a section of code you already have. (If it were identical, you’d 
probably put it into a subprogram.) It is often easier to copy code and modify one version than to 
type two separate, only slightly different, versions. Here is an example of where COPYLINES is 
useful. 


You are working in the Personnel department of your company, and you’re writing a program 
which will need to be run on several Series 200 computers with standard keyboards. Both the 
Model 216 and the Model 236 have 80-column screens, whereas the Model 226 has a 50-column 
screen. This means that the softkey labels must have different lengths. On the Model 226, they are 
eight characters long, and on the Model 216 and Model 236, they are fourteen characters long. In 
the section of code you’re writing you’d like the ON KEY labels to be as descriptive as possible; you 
want to use all fourteen characters if you have them. 


100 

IF P0S(SYSTEM$("CRT ID")t" 

50") THEN ! 50-columns; 

short 

labels 

110 

ON 

KEY 

1 

LABEL 

"MAC SCHD 

" CALL 

Oacation_sched 



120 

ON 

KEY 

2 

LABEL 

"SICK L0" 

CALL 

Sick-leave 



130 

ON 

KEY 

3 

LABEL 

"PAYROLL" 

CALL 

Payroll 



140 

ON 

KEY 

4 

LABEL 

"CRDT UN" 

CALL 

Credit-union 



150 

ON 

KEY 

5 

LABEL 

" WRK HIST 

" CALL 

Work-history 



ISO 

ELSE 






! 8 0 - c o 1 u m n s 5 

1 on S 

labels 

170 

ON 

KEY 

1 

LABEL 

"UACATI0N 

SCHED 

" CALL Vac a t i ori-s c h e d 


180 

ON 

KEY 

2 

LABEL 

"SICK LEAVE" CALL Sick-leave 



190 

ON 

KEY 

3 

LABEL 

"PAYROLL" 

CALL 

Payroll 



200 

ON 

KEY 

4 

LABEL 

"CREDIT UNION" 

CALL Credit-union 



210 

ON 

KEY 

5 

LABEL 

"WORK HISTORY" 

CALL Work-history 



220 

END 

IF 









As you can tell by looking at this code, lines 170 through 210 are almost identical to lines 110 
through 150. Therefore, copying those five lines to the new place and editing the key labels would 
be much faster than retyping the entire line. 

Search and Replace Operations 

The non-programmable FIND command finds all the occurrences of a particular string in a prog¬ 
ram. Suppose, for example, you have a variable called “Tax” in your program, and you want to 
change it to either “State_tax” or “City_tax”, but which one you change it to depends on the 
context of the statement. A FIND command finds each occurrence of the string “Tax”. Once there, 
you can look at the statement and decide whether it should be changed to “State_tax” or “City- 
tax”. 



22 Entering, Running, and Storage Programs 


When a p rogram line has been found, just edit the line in the norma l way and press [ENTER] or 
( RETURN ] . If your change results in a syntax error, correct it and pre ss (ENTER) or ( RETURN ] again; 
the FIND is not cancelled. If you want to delete the line found, press (DEL LN) ; th e line is de leted and 
the FIND is immediately resumed. If you don’t want to change the line, press ( CONTINUE ) , and the 
search resumes where it left off. 

To cancel a search operation before it is finished, press ( t ) , ( I ] , or ( EXECUTE ) . 

Literal replacement is done with the non-programmable CHANGE command. CHANGE is like 
FIND in that it looks through your program and finds occurrences of the spe cified strin g. However, 
it also m akes a ten tative change that you can confirm by pressing (ENTER) or ( RETURN ) , or deny by 
pressing ( CONTINUE ) . If you are positive that you don’t need to verify each replacement, appending 
5 ALL will cause the search-and-replace to be done with no further user intervention. 

Here is an example where you replace one variable name with two variable names: You discover, 
to your dismay, that after writing twenty-five subprograms, all of which use a particular COM 
statement, that you need another variable in the middle of that COM statement. The CHANGE 
command just cries out to be used in this case. Say, for example, that your COM statement looks 
like: 

COM /Hardware/ P1otter_is t P1otter_s pbc$»P rinter_is 

where P1 o 11 e r_ i s is the currently specified device selector for the plotter, Plotter_spec$is 
the plotter specifier and Printer_is is the device selector for the printer. You want to put 
Dump_dev into the COM statement, right after the variable Plotte r_spec$. Your CHANGE 
command could look like this: 

CHANGE "_spec$ »Pri" TO ".spect »DuftiP_deu *P ri " IN 1 >327GG 

Note that the string you’re changing from contains a comma. This helps narrow down the number 
of occurrences that match the string selected and it is desirable for this reason: if you just changed 
Plotte r_spec$ to Plotter_spec$ >D u m p _ d e u, the computer would change all the occurr¬ 
ences you want to be changed, but it would also change many you don’t want to change. In this 
case, you would also cause all the places which either use or define Plotte r.spect to be 
changed, even though you wouldn’t want them to be. You would change 

PI otter_spec$="INTERNAL" 


to 


Plotte r_5Pec$ #Dump_deu = "INTERNAL" 

and this, of course, would cause a syntax error. You will learn efficient ways to specify searches after 
using the command several times. 

To sea rch the entire program, you could either go to the top of program memory with a ( SHIFT) - 
( t ) or use the line range of IN lt327GG. The former method is faster, and fewer keystrokes, 
but if you need to stay in a particular place in memory in order to type a long search key, the latter 
method is useful. 
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Using Subprogram Libraries 

Often, a programmer has a program which is quite large, along with sizable data arrays, and an 
Error 2: Memory Overflow becomes all too common an occurrence. And neither the prog¬ 
ram nor the data can be reduced in any way. There are two keywords, LOAD SUB and DEL SUB 
which address this problem. They are mentioned here because they are part of Entering, Running 
and Storing Programs, which is the subject of this chapter, however, they are not necessary to get 
started. This subject will be covered later. 

See Chapter 6 “User-defined Functions and Subprograms” for a detailed discussion on subprog¬ 
ram libraries. 

Indenting 

INDENT is a non-programmable command which scans the entire program and indents in 
appropriate places. What is meant by “appropriate places” is this: Whenever there is the beginning 
or end of a program statement which causes looping, is conditionally executed, or is a separate 
program segment (subprogram), the first character of each program line contained in that seg¬ 
ment—excluding the line number—is moved to the right or left to make the structure of the 
program more intuitively obvious. For a list of how each kind of statement affects the indentation, 
see the BASIC Language Reference manual. 

An example dealing with the INDENT command’s capabilities follows. This program is not to be 
noted for its efficiency (or lack thereof—the conditions could better be checked with a SELECT 
statement); it is merely for the purpose of demonstrating the INDENT command. The program is 
shown after having been indented with various parameters. Notice how the indented structures 
make it easier to understand the logic flow. 

This example was indented with the command 
INDENT 7,2 

10 FOR 1=1 TO 5 
20 REPEAT 

30 INPUT "How old are you?" .A9e 

40 Reasonable=l ! Assume they're tell ins the truth*•• 

50 IF A S e < 0 THEN 

GO DISP "Aw# c'mon! You can't be "5 ASe 5"yea rs old* You So 11 a be born! 


70 
80 
90 
100 
110 
120 
130 
140 
150 
1 GO 
170 
180 
190 
200 
210 
220 
230 
240 
250 
280 
270 
280 
290 


WAIT 3 
NEXT I 
END 


UNTIL Reasonable 



WAIT 4 


END IF 


ELSE 


END IF 


Reason able = 0 


ELSE 

IF ASe >100 THEN 


IF ASe >120 THEN 

DIS P "Oh# pshaw! I don't believe you* 
R e a s o n a b 1 e = 0 


END IF 
END IF 


DIS P "H m m♦♦♦y o u ' r e well nis h a fossil# huh?" 
ELSE 


ELSE 


IF A S e > 8 0 THEN 


DISP "Glad to meet you* 


DISP "Wow! Most people your aSe don't use computers much 
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And this example was indented with the command 
INDENT 10*1 

10 FOR 1=1 TO 5 

20 REPEAT 

30 INPUT "How old are you?"»A*e 

40 Reason ab 1 e = 1 ! Assume they're tell ins the truth*♦. 

50 IF AsfeCO THEN 

GO DIS P "A w # c 'won! You can't be "5 A S e 5"ye a r s old* You s o 11 a be born! 

11 

70 Re as onab1e = 0 

80 ELSE 

90 IF ASe >120 THEN 

100 DISP "0h # pshaw! I don't believe you*" 

110 Reasonable=0 

120 ELSE 

130 IF Asfe > 100 THEN 

140 DISP "Hmm♦♦♦you ' re well ni$h a fossil# huh?" 

150 ELSE 

ISO IF A*e>GO THEN 

170 DISP "Wow! Most people your aSe don't use computers much*" 

180 ELSE 

190 DISP "Glad to meet you." 

200 END IF 

210 END IF 

220 END IF 

230 END IF 

240 WAIT 4 

250 UNTIL Reasonable 

280 DISP "You we re"5 Ae*3S5♦242198781 5"days old on your last birthday*" 

270 WAIT 3 

280 NEXT I 

290 END 


If one generalizes from the previous examples, the question arises: “What happens if the indented 
code goes completely off the right edge of the screen?” There are two ways that this could 
happen: either the starting column parameter is too large, or the number of nesting levels is too 
great for the specified indentation increment. If, for either of these two reasons, a line of code gets 
longer than the listable length of the machine, an asterisk (*) is placed immediately after the line 
number of that line, and the right end of the line is not visible. 

To correct a problem of program lines longer than the listable length of the machine, execute 
another INDENT statement whose parameters are smaller. 

A program which contains lines longer than 256 characters still executes, STOREs and LOADs 
properly, but if you SAVE the program without correcting the problem, it will not syntax properly 
when you do a GET operation. What is sent to the file is the line number, the asterisk, and as much 
of the program line as possible. The asterisk will prevent the proper syntaxing of the statement 
when the GET is attempted, in addition to the fact that part of the statement is missing. 

Note that you can create a program on one model computer using the maximum line length and 
then get that program and run it on a model with a smaller CRT. You cannot, however, modify any 
program line which is longer than the maximum length for the current CRT without shortening it. 
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When indentation parameters attempt to force program statements to start too far to the right, they 
are bounded by the width of the screen minus eight characters. That is, the first character of a 
program line (excluding the line number) will never start to the right of the screen width - 8. When 
this is attempted, there may be several lines of code (which should differ in indentation) starting in 
column screen width - 8. Therefore, until the nesting level gets back down to a manageable point, 
indentation will be disabled. Note, however, that an internal indentation counter is maintained, so 
statements at the same nesting level will continue to have matching indentation. See the example 
below which was indented with the command 

INDENT 10*15 


Note that this was done on a machine with an eighty-column screen. Had it been done on a Model 
226, with its fifty-column screen, the right-hand limit would have been reached more quickly. 


10 FOR 1=1 TO 5 

20 REPEAT 

30 INPUT "How old are you?"tA^e 

40 Reasonable 2 !.! Assume they're tell in* the 

truth*♦♦ 


50 IF A«fe<0 THEN 

B0 

t be "iA$ei H years old* You a o 11 a be born!" 

70 

80 ELSE 

30 
100 

shaw! I don't belieue you*" 

110 

0 

120 

130 

THEN 

140 

♦♦♦you're well n i $ h a fossil* huh?" 


DISP "Aw > c 'mon! You can' 
Reasonable=0 
IF ASe >120 THEN 

DISP "0h» p 
Reasonable 2 


ELSE 


IF A«fe > 100 
DISP "H mm 


150 

ISO 

THEN 

170 


! Most people 
180 
130 

d to meet you* 
200 
210 
220 
230 
240 
250 
2B0 ■ 


birthday* 


your a si e don't use computers much*" 


END IF 

END IF 
WAIT a 

UNTIL Reasonable 

DISP "You were"5Ase*365*2421987815"days old 


ELSE 

IF Asfe >B0 
DISP "Wow 
ELSE 

DISP "G1 a 

END IF 
END IF 


on your last 


270 WAIT 3 

280 NEXT I 

230 END 


Observe that there are several lines (140 and 160 through 200) which should be indented farther to 
the right. But since the column position of the screen width minus eight is the boundary on the right 
edge, they are not permitted to go as far right as they “should.” Note, however, that indentation 
recovers and is still correct after the point at which they attempt to exceed the right-hand limit. 
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Retrieving a Program 

Programs saved in an ASCII file are retrieved with the GET statement. Programs stored in a PROG 
file are retrieved with the LOAD statement. These statements can be executed from the keyboard 
as commands or included in a program. When executed as commands, they are used to bring a 
program into the computer’s memory so that it can be edited or run. When included in a program, 
they are used to link together the segments of large programs. 

To retrieve a program you need to know the name and type of the file in which it is stored. If you 
are not sure of either of these, execute a CAT command. The catalog display shows the name and 
type of all files on the disc. The options available for ASCII files are discussed first. 

Using GET as a Command 

The GET command is used to bring in programs or program segments from an ASCII file, with the 
options of appending them to an existing program and/or beginning program execution at a 
specified line. To clear any existing program from the computer’s memory and bring in the contents 
of an ASCII file, the command is simply the keyword GET followed by the file name. For example: 

GET "FORMULA" 

This command clears the BASIC program memory and brings in the contents of the ASCII file 
called “FORMULA”, assuming that the file contains valid program lines. If the first line does not 
start with a valid line number, the GET is not performed and an error 68 is reported. If the file is not 
an ASCII file, the GET is not performed and an error 58 is reported. 

Assuming that the file contains valid program lines that were placed in the file by a SAVE operation, 
and their line numbers are still valid after any renumbering that is specified, the lines will be entered 
into program memory. If there is a syntax error in any of the program lines in the file, the lines in 
error are turned into comments, an error 68 is reported, and the syntax error message is sent to the 
system printer. This might happen if the program was written and saved on a computer that had a 
different version of BASIC than the one being used for the GET operation. 

To append the contents of an ASCII file to an existing program, a line identifier is added to the GET 
command. For example, assume that there is a program already in the computer that ends with line 
number 740, and you want to append the contents of a file called “George”. The following 
command could be used. 

GET "Geo r 3e" *750 

This appends the program lines from file “George” to the existing program, renumbering them to 
start with line number 750. If the command GET "George" *100 were used in the same situa¬ 
tion, all existing program lines from 100 to the end of the program in memory would be deleted and 
the contents of file “George” would be appended to the lines that remained at the beginning of the 
program. The program lines in file “George” would be renumbered to start with line 100. 

Sometimes it is not possible to enter a line into the program. This can happen, for example, if the 
specified renumbering would create an invalid line number. In these cases, the line in error is sent to 
the system printer with an error message, but it is not entered into program memory. 
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The GET command can also specify that program execution is to begin. This is done by adding two 
line identifiers: one specifies the placement and renumbering just described, and the other specifies 
the line at which execution is to begin. For example, assume that there is no program in memory 
and that an ASCII file “RATES” contains valid program lines. A typical command to bring the 
contents of this file into memory and begin execution at the first line is: 

GET "RATES">10>10 

If there is already a program in memory, an append and run is allowed. For example: 

GET "RATES" *250,100 

This command specifies that any existing lines from 250 to the end are to be deleted, the contents 
of file “RATES” is to be renumbered and appended beginning at line 250, and then normal 
program execution is to begin at line 100. Although any combination of line identifiers is allowed, 
the line specified as the start of execution must be in the main program segment (not in a SUB or 
user-defined function). Execution will not begin if there was an error during the GET operation. 

Using GET in a Program Line 

The GET statement can be used in a program to transfer execution from one program segment to 
another. When used in a program line, the actions of the GET statement are the same as those 
described for the GET command, except as noted in the following paragraphs. Two examples of a 
programmed GET are shown here. One demonstrates a simple linkage of two program segments, 
as might occur when the entire program is too long to fit in memory. The second shows a simple 
example of keeping a file manager in memory to GET and run various routines. 

A large program can be divided into smaller segments that are connected by using a GET statement 
to move from one to the next. The following short example shows this technique. 

First Program Segment: 


10 

COM Ohms fAfriPS >Uolts 


20 

Ohms = 120 


30 

Oo 11 s = 240 


40 

A m p s = 0 o 11 s / 0 h m s 


50 

GET "wattage" 


B0 

END 


“wattage”: 


10 

COM Ohms »Amps >0olts 


20 

Na11 s = Amps*Oo11 s 


30 

PRINT "Resistor Ohms =" 

5 0 h m s 

40 

PRINT "Resistor Wattage 

= "5 W a 11 s 

50 

END 
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One important point to note is the use of a COM statement. The COM statement places 
variables in a section of memory that is preserved during the GET operation. Since the program 
saved in the file “wattage” also has a COM statement that contains three REAL scaler variables, 
the values assigned to those variables in the previous program segment are preserved. If the 
program segments did not contain equivalent COM statements, all variables in the mismatched 
COM blocks would be rendered undefined by the prerun that is preformed after the GET 
operation. Therefore, to effectively use the GET statement to link program segments, all vari¬ 
ables that need to be preserved must be placed in COM statements, and all program segments 
using those variables must have equivalent COM statements. 

Note also the form of the GET statement. If this particular statement were executed from the 
keyboard, no program execution would take place. However, the computer understands that a 
GET in a program is meant to cause execution to resume. When no parameters are specified in 
a programmed GET, the entire old program segment is replaced by the new segment, and 
execution resumes with the first line in the new program segment. 

If a single line identifier is used in a programmed GET (such as GET " f o rmat" > 150), the last 
part of the old program segment is deleted (from the specified line to the end), the new program 
segment is renumbered and appended to the remaining portion of the old segment, and 
execution resumes with the first line of the resulting program. If two line identifiers are specified, 
the action is the same as described for the GET command from the keyboard. In these cases, it 
is usually not necessary to repeat the COM statement in the second program segment. Since 
the COM statement is usually in the first (undeleted) part of the program, it remains after the 
second segment is in place. If there are two identical COM statements in the same program 
context, an error 12 results. Program segments that are linked in with the GET statement should 
repeat the original COM statement only if that original COM statement is deleted as a result of 
the GET operation. 

An example of programming a GET statement with two line identifiers is a “file executive” 
program that gets and runs other program files. This technique is sometimes used when most of 
the computer’s memory is needed to store data and the various program files perform indi¬ 
vidual operations on that data. A small example of the general technique follows. Admittedly, 
the tasks shown are all simple enough to be contained in a single program with plenty of room 
left for data. The example merely demonstrates the structures involved with this type of file 
linking. 

In this example, a large portion of memory is used to hold weights input from an electronic 
scale. The “file executive” gives the operator a menu of operations to choose from and gets the 
requested file. The requested file performs its task and returns control to the “executive”. The 
individual tasks shown here are the printout of the weights and the statistical analysis of the 
weights. Assumed, but not shown, is a routine that entered the weights from the scale and 
stored them in the array. (The input of data from external devices is covered in the BASIC 
Interfacing Techniques manual.) 
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Main Executive: 


100 

110 

120 

130 

140 

150 

ISO 

170 

180 

185 

190 

200 

210 

220 

230 

240 

250 

280 

270 

280 

290 

300 

310 

320 

330 


This program manages the utility files for 
some hypothetical data* Data was stored 
in the REAL array "Weights"* The device 
selector for the external printer is 
is assigned in line 200* Each utility 
file sends control bacK to line “Start" 
when it is done* The program disc must be 
present when this executive is used* 


OPTION BASE 1 

COM Wei3hts(5000) ^Samples >Printer 

Printer=701 ! External printer for data 

Samples=5000 ! Also see array declaration 

i 


Starts ! Main entry point 

PRINTER IS 1 ! For program messages 

PRINT 

PRINT “Enter P to print weights" 

PRINT "Enter A for an analysis" 


Ask: INPUT "Enter Command Letter"*In$ 

IF In $ ="P" THEN GET "Prin tout" #330#330 
IF In $ ="A" THEN GET "An a 1ysis" #330#330 
GOTO Ask ! Incorrect entry 

END 


File “Printout”: 


100 ! This routine prints the data in the array 

110 ! “Weights" to an external printer* 

120 ! Necessary variables are initialized in 

130 ! the main executive* 

140 ! 

150 PRINTER IS Printer 

180 FOR 1=1 TO Samples 

170 PRINT "Sample #"515" 

180 NEXT I 
190 PRINT CHR$(12) 

200 GOTO Start 
210 END 


! Use external printer 
! Print all weights 
weighs"5Weiahts(I) 

! Form-feed 
! Return to executive 
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File “Analysis”: 


100 ! This routine finds the mean and standard 

110 ! deviation of the data in 11 W e i 3 h t s " ♦ 

120 ! Necessary variables are initialized in 

130 ! the main executive* 

140 ! 

150 Sumx=0 ! Clear sum of X 

ISO Sumx2 = 0 ! Clear sum of X squared 

170 FOR 1=1 TO Samples ! Calculate summations 

180 Sumx = Sumx + Wei$h t s(I) 

190 Sumx2 = Sumx2 + Wei3h t s(I)“2 

200 NEXT I 

210 Me an = Surn x/S am p1e s 

220 St d d e v = SQR((Sumx2-Sumx"2/Samp 1e s)/(Samp 1e s- 1 ) ) 

230 PRINT 

240 PRINT "Number of samples =" 5Samples 

250 PRINT "Mean weight ="5Mean 

2 G 0 PRINT "Standard deviation ="5 S t d d e v 

270 GOTO Start ! Return to executive 

280 END 


Notice that any information that is shared by all the routines is placed in COM. The individual 
task files do not contain COM statements because the COM statement in the executive routine 
is never deleted. Values that are shared by all routines are initialized by the executive. In that 
manner, a standard characteristic can be changed in the executive, with no alterations required 
in any of the other files. The “shared” values used in this example are the number of weights in 
the array (Samples) and the device selector of the external printer (Printer). 

Using LOAD as a Command 

The LOAD command is used to bring in programs from a PROG file, with the option of 
beginning program execution at a specified line. To clear any existing program from the compu¬ 
ter’s memory and load the contents of a PROG file, the command is simply the keyword LOAD 
followed by the file name. For example: 

LOAD "Cannon" 

This command clears the program memory and brings in the contents of the PROG file called 
“Cannon”. If the file is not a PROG file, the LOAD is not performed and an error 58 is reported. If 
any lines require a language extension that is not currently installed, those lines cannot be executed. 
However, the LOAD proceeds without error. 

The LOAD command can also specify that program execution is to begin. This is done by 
adding a line identifier. For example: 

LOAD "STONE">10 

This command causes the computer to load the program in file “STONE” and begin execution 
at line 10. The line identifier may be a label or a line number, but it must identify a line in the 
main program segment (not in a SUB or user-defined function). 
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The LOAD command cannot be used to bring in arbitrary program segments or append to a main 
program like GET can. Subprogram segments can be appended using the LOADSUB command. 
This is described in Chapter 7. 

Using LOAD in a Program Line 

When used in a program line, the actions of the LOAD statement are the same as those described 
for the LOAD command, except program execution resumes whether a line identifier is specified or 
not. For example: 

120 LOAD "PART2" 

When this program statement is executed, the existing program is replaced by the contents of the 
PROG file called “PART2” and program execution resumes with the first line in the new program. 
When a line identifier is included in a programmed LOAD statement, execution resumes with the 
specified line after the file is loaded. 

Remember to include in a COM statement any variables that must be shared by more than one 
program segment. The COM statement must be present before and after the LOAD if you want all 
the data in COM to be preserved. The section describing GET has an example of using COM to 
preserve data. 

Autostart of a PROG File 

Your computer can be configured to LOAD and RUN a program automatically when the power is 
switched on. To use this feature, STORE a PROG file called “AUTOST”. Then when the power is 
switched on, the computer automatically loads that file and begins executing the program from the 
first line. No action is taken if there is no “AUTOST” file present. 

If you want to give your program file a more meaningful name than “AUTOST”, create an 
“AUTOST” file that simply loads the desired file. For example, if you want to autostart a program 
called “ALARM”, store this in the “AUTOST” file: 

10 ! This is the AUTOST file for program ALARM 

20 LOAD "ALARM" 

30 END 

On a dual-drive machine like the Model 236, the autostarted program is not restricted to the space 
remaining on the language system disc because there are two disc drives. A short AUTOST file on 
drive 0 can load a long program file from drive 1. The following example shows this technique. 

10 ! This is the AUTOST file for program ALARM 

20 MASS STORAGE IS ":INTERNAL >4 > 1 " 

30 LOAD "ALARM" 

40 END 

By using the appropriate mass storage unit specifier, this general technique can be extended to use 
external disc drives. 
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The AUTOST program can also load the BIN files automatically. For example, 


10 

IThis 

> i s 

the AUTOST file 

20 

LOAD 

BIN 

"DISCrHP *702 11 

30 

LOAD 

BIN 

"HPIBsHP*702" 

40 

MASS 

STORAGE IS "s HP *702 

50 

LOAD 

BIN 

"MS" 

GO 

LOAD 

BIN 

"10" 

70 

LOAD 

BIN 

"GRAPH" 

80 

END 




Be sure to load the drivers for the mass 
BINs. 


.'Specify if different from where SYSTM 
! was loaded* 


storage device and the card driver before you load the other 


If you load BASIC from an SRM, the system looks for a file in the SYSTEMS directory named 
AUTOSTNN where NN is your node number. If this file is not found, the system looks for a file 
named AUTOST in the root directory. 
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System Configuration 

The BASIC Language System is contained in several files. The SYSTM file contains what is 
sometimes called “core” BASIC. Extensions to core BASIC and device drivers are in BIN files. The 
language extensions add statements to BASIC. For example, the PDEV extension gives you the 
MOVELINES and COPYLINES commands. The device drivers allow you to use mass storage 
devices other than the internal discs and memory. Whenever you need an extension for an 
example in this manual, the BIN file name is given. 

Loading BINs 

As shown in the previous example, you load an extension or driver with the LOAD BIN statement. 

LOAD BIN "GRAPH)': HP >700" 

LOAD BIN "ERR" 

LOAD BIN "DISC:INTERNAL >4 »1" 

If you attempt to execute a statement that requires a language extension, error 1 occurs. You can 
load the required BIN and then continue your programming. 

You can LOAD a STOREd program that requires language extensions not present in the computer, 
but you cannot run it. Error 1 occurs and the option number, or extension name if ERR is loaded, is 
displayed. The option numbers are listed in the Useful Tables section of the BASIC Language 
Reference manual. 

You can GET a SAVEd program that requires language extensions, but errors occur during the 
GET. Each statement that requires a missing option is made a comment. An ! is placed before the 
line. You can load the missing BIN and then edit the program. 

Storing the System 

Once you have all the BINs in memory, you may want to save that configuration for the next time 
you boot up the system. The STORE SYSTEM command stores core BASIC and all the BINs into 
one file. 

STORE SYSTEM "SYSTEM-B:HP>702 * 1 " 

STORE SYSTEM "SYSTEM.2:REMOTE" 

STORE SYSTEM "SYS-MINE" 

The boot ROM looks for a SYSTM file which begins with “SYSTEM-”. A 3.0 and 4.0 ROM also 
looks for SYSTM files which begin with “SYS_”. A SYSTM file which has a different prefex cannot 
be booted. If there is more than one loadable file, and you press the space bar on the keyboard 
after power up and before the file is loaded, all loadable files are listed. You can choose the one you 
want loaded. If you do not press the space bar, the boot ROM loads the first SYSTM file it finds. 

Since core BASIC uses most of a 5 Vi - inch flexible disc, you cannot store more than one system 
on the disc. You also cannot store several BINs with core BASIC on this disc. 

Scratching BINs 

You can delete the BINs from memory with the SCRATCH BIN statement. This statement deletes 
all the BINs, except the one which drives the CRT. Note that it also scratches any program in 
memory. 
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Other Mass Storage Operations 

The general mass storage capabilities of the computer are discussed in Chapter 7. Because many of 
the operations are applicable to program files as well as data files, certain operations are summa¬ 
rized here. If these brief examples do not provide sufficient information, refer to Chapter 7 for more 
details. 

The name of a file can be changed without disturbing the file’s contents. This is done with the 
RENAME statement. For example, to change the name of a file from “George” to “Frank”, use the 
statement: 

RENAME "GeorSe" TO "Frank" 

A file entry can be removed from the disc directory with the PURGE statement. This prevents any 
further access to the file. For example: 

PURGE "Mvfile" 

This statement eliminates the file “Myfile” from the disc directory. 

A file can be given a protect code by using the PROTECT statement. A protect code is a 2-character 
string that must be specified to modify the file, but it does not appear in the catalog display. For 
example, to protect the file “SECRET” with the protect code “BS”, use this statement: 

PROTECT "SECRET" CBS” 

The protect code is placed after the file name to allow access. For example, to PURGE the 
previously protected file “SECRET”, the statement is: 

PURGE "SECRET<BS >" 

Files can be copied with the COPY statement. Some examples: 

COPY "MYPROG" TO "MYPROG:INTERNAL >4 »1 " 

COPY "MYPROG:HP8230X >700 >0" TO "MYPROG:HP8290X>700>1" 

These statements create a backup copy of the file MYPROG. The first example copies from the 
right-hand drive to the left-hand drive on a Model 236. The second example copies a file from the 
left-hand drive to the right-hand drive on an external device such as the HP 82901 or HP 9121. 
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Softkeys 

There is a set of keys on your keyboard labeled either ( to ) thru ( fa ) or ( f\ ) thru ( ) . 

These are softkeys. You can define the function of these keys as typing aids. That is, you define one 
softkey to contain any combination of keystrokes. You may include all the ASCII characters, as well 
as non-ASCII keys, such as arrow keys, insert and delete character, continue, etc. This has nothing 
to do with programmatic ON KEY definitions; they are discussed in future chapters. 

The KBD extension is required to use typing aids. When you load KBD, the typing aids are given 
default definitions. These default definitions includ e som e co mmonl y used commands. For exam¬ 
ple, ( ks ) and ( 11 ) are defined as SCRATCH. ( ) and ( (5 ) are defined as CAT. You can 

see the definitions in the softkey menu on your display. 

If you have an HP 46020A keyboard, your softkeys are labeled ( 1\ ) thru ( /8 ) . There are 
System defined softkeys and User softkeys. You cannot change the definitions for the System keys. 
These keys represent physical keys on other keyboards. There are three sets of Users softkeys 
which gives you 24 definable softkeys. You can change any of them. In general, the menu which is 
displayed shows the definitions of the softkeys. To change the menu and the definition, press the 
( SHIFT ) and ( Menu ) keys. To go from the User menu to the System menu (or System to User) press 
the ( User ) / (System) key. 

If you have the HP 98203A keyboard (the standard keyboard fo r the M odel 216), you have five 
softkeys. Each softkey can have two definitions. When you press ( SHIFT ) and a soft key, yo u access 
( kp ) thru ( k 4 ) . When you press just the softkey, you access ( ks ) thru ( fa ) . All ten 
definitions are displayed on the menu. 

If you have the HP 98203B keyboard (the standard keyboard for the Model 236), you ha ve ten 
softkeys labeled ( kp ) thru ( k 9 ) . These keys also have a shifted version. When you press ( SHIFT ) 
and a softkey, you access ( kio ) thru ( ki 9 ) . The softkey menu displays the first 10 softkey 
definitions. The second 10 definitions cannot be displayed. 

Default Softkey Definitions 

Several typing aid definitions are loaded when you load KBD. These definitions are loaded for your 
convienence. You can change the definitions, load your own definitions or delete the definitions. 
The following sections explain how you do this. 

Defining Softkeys 

To define a typing aid, type EDIT KEY and the number of the softkey you want to define. For 
example, 

EDIT KEY 2 

You could also press ( EDIT ) ( k 2 ) or ( EDIT ) ( f2 ) , which is the same as the EDIT KEY com¬ 
mand. 

When you execute this command, the following message is displayed: 

Editing Key 2 

If softkey 2 is currently defined, its definition is displayed. If it is not defined, the input line is blank. 
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To enter the new de finition , use the keyboard. Type ASCII characters directly. To get non-ASCII 
keystrokes, use the ( CTRL ) key and the function key you want to use. For example type the 
following: 

( . CTRL) - ( CLRLN ) ( L ) ( I )( S ) ( T ) ( CTRL) - ( EXECUTE ) 


Note 

This technique will not work for some non-ASCII keys on an 
HP 98203A keyboard. To enter non-ASCII keystrokes, refer to the 
Second Byte of Non-ASCII Key Sequences table in the U seful Table 
section of the B ASIC Language Reference manual. Press (ANY CHAR) 
( 2 } ( 5 ) ( 5 ) followed by the character associated with the 

desired key. 


(You may have keys other than ( CLR LN ) or ( EXECUTE ) . Use the key which means clear line and 
execute or return.) 

By pressing ( CTRL ) and ( CLR LN ) together, you get Q#. ( CTRL) - ( EXECUTE ) gives you QX. The Q 
means yo u have pressed a system key. The # or X means you have pressed ( CLR LN 1 or 

( EXECUTE ) . 

Now, press (ENTER) or ( RETURN ) . The definition is stored and the softkey menu changes. 

Press ( k 2 ) or ( (2 ) . 

The LIST command is entered on the input line and then executed. You may not be able to see the 
command displayed because it is executed immediately. 

If you do not want the command executed, leave out ( CTRL ) - ( EXECUTE ) . 

Besides commands, you can define the softkeys to display any sequence of characters. For exam¬ 
ple, if you are writing a program and want to separate each subprogram with a line of asterisks you 
could define a softkey to do this. 

! ******************************** (ENTER) 

If a ( CLR LN ) is the first character in the definition, it will not show in the label. If you want a softkey 
label which “looks nice” - it doesn’t have a lot of inverse-video Ks in it - you can have the visible 
character be an aesthetically pleasing label, the next thing a ( CLR LN ) , which erases the label which 
prints when the key is invoked, and the next n characters be the functional “core” of what the key is 
supposed to do. The result of this strategy is that when you press a softkey, the aesthetically- 
pleasing label is displayed, immediately e rased , and the characters following the label are displayed 
and, if you specified, processed with an (ENTER) , ( EXECUTE ) or ( RETURN ) , etc. 
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Softkey Definitions 

There is 1024 bytes of memory set aside for softkey definitions. Since there is a certain amount of 
overhead necessary for each one, there are approximately one thousand characters available for 
softkey definitions. 

The maximum number of characters which may be entered in a definition is two full CRT lines. If 
you define the softkeys on one Series 200 and store the definitions, you can load the definitions on 
another Series 200 even if the definitions are greater than two of the loading computer’s CRT lines. 
You will not be able to modify the long definitions, but you can delete the old and enter a new 
definition. Attempting to use an overlong typing aid will cause the typing aid buffer to overflow. 
Some characters will be lost. 

Listing Softkey Definitions 

You can list the softkey definitions. All of the currently defined softkeys are listed. To list to the 
system printer execute: 

LIST KEY 

To specify a device that is not the current system printer, include a device selector in the command. 
To send the listing to the printer execute: 

LIST KEY »PRT 

The listing does not look like what you typed for the definition if you included system keys. Since 
most printers cannot print an inverse video K, the term System key: i s listed . Each system key is 
listed on a separate line. For example, if you entered the definition for ( k 2 ) in the first example, 
your listing is: 

Key 2: 

S y s t e m K e y s » 

LIST 

S y s t e iti k e y : X 

Softkey Files 

When you have the typing-aid softkey definitions as you want them, you can store them on a file 
which can be loaded at your convenience. To store the currently-defined typing-aid definitions onto 
a file, use a STORE KEY command. For example, the following commands store the current key 
definitions onto a file called AIDS: 

STORE KEY "AIDS" 

or 

RE-STORE KEY "AIDS" 

Later, when you want to load those definitions you stored, type: 

LOAD KEY "AIDS"- 

Executing a LOAD KEY command without a file name causes the default, power-up definitions to 
be restored. 
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Defining Softkey Files Programmatically 

When you type STORE KEY "KEYS", the computer takes the current softkey definitions, and 
writes them to a BDAT file in a format which can be understood by a LOAD KEY command. The 
LOAD KEY command, however, doesn’t know (or particularly care) how that BDAT file got there, 
as long as it’s in the correct format. 

The correct format for key definitions on file is this: 

• The file must be a BDAT (Binary DATa) file. 

• The file must be created with FORMAT OFF. This causes the data to be written to the file in 
internal format, not ASCII representation. 

• Each key’s data consists of an integer (the key number—zero through twenty-three) followed 
by a string—the key’s value. 

See the example program below. Note that all of the keys do not have to be put onto the file, nor 
do the key definitions sent to the file have to be in numerical order. 


10 ! File "DoKe/File". ! 

20 DIM Key_value$[160] ! 

30 INTEGER Key_number ! 

40 CREATE BDAT "SOFTKEYS“ .3 ! 

50 ASSIGN @Keys TO "SOFTKEYS" ! 

GO FOR 1=0 TO 9 ! 

70 READ Key-number »Key-yalue$ ! 

80 OUTPUT @Keys5Key_number»Key_va 1ue$ ! 

90 NEXT I ! 

100 ASSIGN ©Keys TO * ! 

110 LOAD KEY "SOFTKEYS" ! 

120 ! - Key data - 

130 DATA 9»"work!"»5 » " t h a t "*8>"would">0»"You" 
#3>"told" »6»" this" 

140 END 


Name of file which holds program 
In case you have a LONG key def♦ 
Must be 1B - b it key number 
Create a 3-record BDAT file 
Open file (FORMAT OFF is default) 
First ten keys*.* 

Get key number and definition 
Write them to the file 
et cetera 

Write EOF t close the file 
See if it worked 


»4»"you" >7#"thin a" #2»"I" »1 »"see?" 


In this way, a program can define made-to-order typing-aid key definitions. 
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Clearing the Computer 

When power is first switched on and the language system is loaded, the memory is clear and 
various system elements are assigned default values. (For example, the CRT is assigned as the 
system printer.) This condition is called the “power-on state” of the computer. A detailed list of the 
conditions established at power-on is given in the “Useful Tables” chapter at the back of the BASIC 
Language Reference. Turning power off, then back on again is one way to clear the computer’s 
memory. However, this is not necessary and often is not convenient. 

The most useful method of clearing the computer is to use the SCRATCH command. There are 
four forms of this command to allow a choice of clearing actions. The following paragraphs give the 
details of the choices. 

SCRATCH — This command clears all program statements from the computer’s memory. It also 
clears any data which has not been placed in COM (see Chapter 6 for a description of 
COM). 

SCRATCH C — This command clears all variables from the computer’s memory, including COM 
variables. 

SCRATCH A — This command clears almost everything from the computer’s memory. The only 
exceptions are the recall buffer, the real-time clock and BINs. 

SCRATCH BIN — This command clears all BINs except the one which drives the CRT from the 
computer’s memory. It also performs a SCRATCH A. 

SCRATCH KEY — This allows you to clear individual softkeys, or all of them at once. If you 
want to scratch a particular key, you can do this two ways. The following example clears 
the typing-aid definition for softkey 4. 

• SCRATCH KEY 4, or 

• SCRATCH ! k4 ) 

To erase all softkey definitions, execute 
SCRATCH KEY 

No SCRATCH commands are allowed in a program, and they may not be executed while a 
program is running. 
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Program Structure and How 


Chapter 

~ 3 ~ 


Introduction 

Two of the most significant characteristics of a computer are its ability to perform computations and 
its ability to make decisions. If the execution sequence could never be changed within a program, 
the computer could do little more than plug numbers into a formula. Series 200 computers have 
powerful computational features, but the heart of a computer’s intelligence is its ability to make 
decisions. 

The computational power of your computer is exercised as it evaluates the expressions contained in 
the program lines. Chapters 4 and 5 present the various data manipulation tools available. The 
decision-making power is used to determine the order in which lines will be executed. This chapter 
discusses the ways of controlling the “flow” of program execution. 


The Program Counter 

The key to the concept of decision making in a computer is an understanding of the program 
counter. The program counter is the part of the computer’s internal system that tells it which line to 
execute. Unless otherwise specified, the program counter automatically updates at the end of each 
line so that it points to the next program line. This is illustrated in the following drawing. 


Value in Program Counter 
Program Lines at End of Line 


120 R = R + 2 

130 Area=PI*R"2 

131 PRINT R 

140 PRINT "Area 
150 STOP 


| 130 

131 

140 

= " 5 A re a | 150 

|don’t care 


This fundamental type of program flow is called “linear flow”. As shown by the arrow, you can 
visualize the flow of statement execution as being a straight line through the program listing. 
Although linear flow seems very elementary, always remember that this is the computer’s normal 
mode of operation. Even experienced programmers are sometimes embarrassed to discover that a 
“bug” in their program was caused by the simple incrementing of the program counter into the 
wrong portion of the program. 

As stated in the introduction of this chapter, a computer would be little more than a glorified adding 
machine if it were limited to linear flow. There are three general categories of program flow. These 
are sequence, selection (conditional execution), and repetition. In addition to capabilities in all 
three of these categories, your computer also has a powerful special case of selection, called 
event-initiated branching. The rest of this chapter shows how to use all of these types of program 
flow and gives suggestions for choosing the type of flow that is best for your application. 
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Sequence 

Linear Flow 

The simplest form of sequence is linear flow. The preceding section showed an example of this 
type of flow. Although linear flow is not at all glamorous, it has a very important purpose. Most 
operations required of the computer are too complex to perform using one line of BASIC. 
Linear flow allows many program lines to be grouped together to perform a specific task in a 
predictable manner. Although this form of flow requires little explanation, keep these character¬ 
istics in mind: 

• Linear flow involves no decision making. Unless there is an error condition, the program 
lines involved in this type of flow will always be executed in exactly the same order, 
regardless of the results of or arguments to any expression. 

• Linear flow is the default mode of program execution. Unless you include a statement that 
stops or alters program flow, the computer will always “fall through” to the next higher- 
numbered line after finishing the line it is on. 

Halting Program Execution 

One of the obvious alternatives to executing the next line in sequence is not to execute 
anything. There are three statements that can be used to block the execution of the next line 
and halt program flow. Each of these statements has a specific purpose, as explained in the 
following paragraphs. 

Chapter 2 defined a main program as a list of program lines with an END statement on the last 
line. Marking the end of the main program is the primary purpose of the END statement. 
Therefore, a program can contain only one END statement. The secondary purpose of the END 
statement is stopping program execution. When an END statement is executed, program flow 
stops and the program moves into the stopped (non-continuable) state. 

It is often necessary to stop the program flow at some point other than the end of the main 
program. This is the purpose of the STOP statement. A program can contain any number of 
STOP statements in any program context. When a STOP statement is executed, program flow 
stops and the program moves into the stopped (non-continuable) state. Also, if the STOP 
statement is executed in a subprogram context, the main program context is restored. (Subpro¬ 
grams and context switching are explained in Chapter 6.) 

As an example of the use of STOP and END, consider the following program. 


100 

Radius 

= 5 

110 

Ci rcuM 

=PI*2*Radius 

120 

PRINT 

I NT ( C i rcuni) 

130 

STOP 


140 

A re a = P 

I * R a d i u s " 2 

150 

PRINT 

INT(Area) 

1B0 

END 



When the ( RUN ) key is pressed, the computer prints 31 on the CRT and the Run Indicator (lower 
right corner of CRT) goes off. This first press of the R UN key caused linear execution of lines 100 
thru 130, with line 130 stopping that execution. If the ( RUN ) key is pressed again, the same thing 
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will happen; the program does not resume execution from its stopping point in response to a RUN 
command. However, RUN can specify a starting point. So, execute RUN 140. The computer prints 
0 and stops. This command caused linear execution of lines 140 thru 160, with line 160 stopping 
that execution. However, a RUN command also causes a prerun initialization (see Chapter 2 if this 
is an unfamiliar term) which zeroed the value of the variable Radius. 

You could try pressing ( CONTINUE ) in the preceding example, but you will get an error. A stopped 
program is not continuable. This leads up to the third statement for halting program flow. 
Replace the STOP statement on line 130 with a PAUSE statement, yielding the following 
program. 

10 0 R a d i u s = 5 

110 Circum=PI*2*Radius 

120 PRINT INT(Circum) 

130 PAUSE 

140 Area = PI*Radius "2 
150 PRINT I NT(A re a) 

1B0 END 


Now press ( RUN ) , and the computer prints 31 on the CRT. Then press ( CONTINUE ) , and the 
computer prints 78 on the CRT. The purpose of the PAUSE statement is to temporarily halt 
program execution, leaving the program counter intact and the program in a continuable state. 
One common use for the PAUSE statement is in program troubleshooting and debugging. This 
is covered in Chapter 12. Another use for PAUSE is to allow time for the computer user to read 
messages or follow instructions. Interfacing with a human is covered in greater depth in Chapter 
14, but here is one example of using the PAUSE statement in this way. 


100 
110 
120 
130 
140 
150 
1 BO 
170 
180 


PRINT "This program Generates a cross-reference" 
PRINT "printout. The file to be cross-referenced" 
PRINT "must be an ASCII file containing a BASIC" 
PRINT "pros ram. " 

PRINT 

PRINT "Insert the disc with your files on it and" 
PRINT "press CONTINUE." 

PAUSE 

! Pros ram execution resumes here after CONTINUE 


Lines 100 thru 16 0 are i nstructions to the program user. Since a user will often just load a 
program and press ( RUN ) , the programmer cannot assume that the user’s disc is in place at the 
start of the program. The instructions on the CRT remind the user of the program’s purpose 
and review the initial actions needed. The PAUSE statement on line 170 gives the user all the 
time he needs to read the instructions, remove the program disc, and insert the “data disc”. It 
would be ridiculous to use a WAIT statement to try to anticipate the number of seconds 
required for these actions. The PAUSE statement gives freedom to the user to take as little or as 
much time as necessary. 

When ( CONTINUE ) is pressed, the program resumes with any necessary input of file names and 
assignments. Questions such as “Have you inserted the proper disc?” are unnecess ary now. 
The user has already indicated compliance with the instructions by pressing ( CONTINUE ) . 
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Simple Branching 

An alternative to linear flow is branching. Although conditional branching is one of the building 
blocks for selection structures, the unconditional branch is simply a redirection of sequential 
flow. The keywords which provide unconditional branching are GOTO, GOSUB, CALL, and 
FN. The CALL and FN keywords invoke new contexts, in addition to their branching action. 
This is a complex action that is the topic of an entire chapter (Chapter 6). This section discusses 
the use of GOSUB and GOTO. 

Using GOTO 

First, you should be aware that the structuring capabilities available in BASIC make it possible to 
avoid the use of the unconditional GOTO in most applications. You should also be aware that this is 
a highly desirable goal. The problem is not anything inherent in the GOTO statement. The problem 
lies in the programmer’s tendency to “glue together” pieces of an algorithm, using more and more 
GOTOs with each revision. Then comes that inevitable day when a fatal bug reveals that it is 
impossible to “GET BACK FROM” the last “GO TO”. The excessive use of GOTO has been 
appropriately named spaghetti coding. Keep this very descriptive term in mind when you are 
deciding whether to “just throw something together” or “do it right the first time”. (See the section 
on “Top-Down Design” in Chapter 6.) 

The only difference between linear flow and a GOTO is that the GOTO loads the program 
counter with a value that is (usually) different from the next-higher line number. The GOTO 
statement can specify either the line number or the line label of the destination. The following 
drawing shows the program flow and contents of the program counter in a program segment 
containing a GOTO. 


Value in Program Counter 
Program Lines at End of Line 



R = R + 2 

1 190 | 

Area=PI*R"2 

| 200 | 

GOTO 240 

240 | 

Midth=Width+l 

r 220 1 

Leri3th = LenSth + l 

| 230 1 

Area=Width*Len3th 

i 240 | 

PRINT "Area ="5Area 

250 | 

GOTO 210 

f2i0~1 


As you can see, the execution is still sequential and no decision making is involved. The first 
GOTO (line 200) produces a forward jump, and the second GOTO (line 250) produces a 
backward jump. A forward jump is used to skip over a section of the program. An unconditional 
backward jump can produce an infinite loop. This is the endless repitition of a section of the 
program. In this example, the infinite loop is line 210 thru 250. 


An infinite loop by itself is not usually a desirable program structure. However, it does have its 
place when mixed with conditional branching or event-initiated branching. Examples of these 
structures are given later in this chapter. 

Using GOSUB 

The GOSUB statement is used to transfer program execution to a subroutine. Note that a sub¬ 
routine and a subprogram are very different in HP BASIC. Calling a subprogram invokes a new 
context. Subprograms can declare formal parameters and local variables. A subroutine is simply a 
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segment of a program that is entered with a GOSUB and exited with a RETURN. Subroutines are 
always in the same context as the program line that invokes them. There are no parameters passed 
and no local variables. If you are a newcomer to HP’s BASIC, be careful to distinguish between 
these two terms. They have been used differently in some other programming languages. 

The GOSUB is very useful in structuring and controlling programs. The similarity it has to a 
procedure call is that program flow can automatically return to the proper line when the 
subroutine is finished. The GOSUB statement can specify either the line label or the line 
number of the desired subroutine entry point. The following drawing shows the program flow 
and contents of the program counter in a program segment containing a GOSUB. 


Value in Program Counter 

Subroutine Program Lines at End of Line Program Lines 


Value in Program Counter 
at End of Line 


1000 
10 1 0 
1020 
1030 
1040 


PRINT Area! "square in* 

Cent=Area*G*451G 

PRINT Cent 5 "square cm" 

PRINT 

RETURN 



R = R + 2 I 310 | 

Area = PI#R A 2 r~320~| 

GOSUB 1000 HOOP] 

Width=Width+l 1 340 | 

Lenath = Lensfth + l | 350 | 


! Pro?raw continues 


Program execution is sequential and no decision making is involved. The main reason that a 
GOSUB is a more desirable action than a GOTO is the effect of the RETURN statement. The 
RETURN statement always returns program execution to the line that would have been ex¬ 
ecuted if the GOSUB had not occurred. This is especially useful when using an event-initiated 
GOSUB. Since it is usually impossible to predict when a user might press a softkey (for 
example), it is usually impossible to predict what program line should be returned to at the end 
of a service routine. By using GOSUB and RETURN, the computer does the work for you. 

Another common advantage gained from the use of GOSUB is program economy resulting 
from the consolidation of common tasks. For example, assume that you are writing a page 
formatter program to neatly print letters, reports, etc. The actions taken at the end of each page 
might be such things as: 

1. Skip two blank lines 

2. Print the page number 

3. Update the page counter 

4. Print a form-feed 

5. Zero the line counter 


These end-of-page actions might be necessary at many places in the program. For example: in 
the new-page segment, in the conditional-page algorithm, in the normal line-printing segment, 
and in the end-of-file process. It would be wasteful duplication to repeat all those end-of-page 
steps every place they are needed. 

That kind of duplication also opens the door to updating problems. Suppose that you wanted to 
modify the end-of-page action to make it print line-feeds instead of a form-feed for the benefit 
of a printer that doesn’t use form-feeds. If you had duplicated the end-of-page routine in five 
different places in the program (or was that six?), you will be doing five times as much typing to 
make the change, and you will probably miss a spot. 
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The solution is a subroutine. For the sake of completeness in this example, the hypothetical 
end-of-page subroutine is shown below. 

540 End_pa3e: ! 

550 PRINT USING "2/»K"SPaSenumber 

5B0 Pa Sen Limb e r = Pa den urn be r+1 

570 PRINT CHR$<12)5 

580 L i n e s = 0 

590 RETURN 

There are no “rules” to say when a program action should be made into a subroutine and when 
it should be left in linear-flow. The following suggestions may help you decide. 

• There is no significant speed penalty for using a subroutine. The time required to process 
the GOSUB and RETURN is extremely small. If you are having trouble getting your 
application to run fast enough, it is doubtful that your problems will be solved by removing 
a couple of GOSUBs. In fact, the resulting loss of “readability” may actually make it more 
difficult to identify and correct the real problem in timing. 

• The “cross-over point” in line overhead is a subroutine that is only three lines long and is 
called from only two places in the program. In other words, it takes the same number of 
program lines to duplicate three lines as it does to stick a RETURN on the end of them and 
add two GOSUB statements. However, there is nothing “magical” about this observation. 
It does not mean that you shouldn’t have a subroutine shorter than three lines, or that you 
should go around making a subroutine out of every three-line sequence you see repeated. 
It should simply make you aware of possible improvements that could be made if you see 
the same sequence repeated in several places in your program. 

• Decisions about subroutines are best made on a conceptual level. Although there is noth¬ 
ing wrong with accidentally discovering that you repeated ten lines which would make a 
good subroutine, it is better to identify the appropriateness of subroutines during planning. 
One question to ask yourself is, “Does it make sense to handle this task in a subroutine?” If 
it takes a dozen flags and status variables to select all the variations that are needed from 
one call to the next, a subprogram is probably a cleaner solution. Lines of code that “just 
happen” to be repeated in several places are not good candidates for a subroutine. A 
subroutine should have some identifiable task, like opening a file, normalizing a variable, 
processing an end-of-page, decoding a keypress, parsing a string, and so forth. 
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Selection 

The heart of a computer’s decision-making power is the category of program flow called selection, 
or conditional execution. As the name implies, a certain segment of the program either is or is not 
executed according to the results of a test or condition. This is the basic action which gives the 
computer an appearance of possessing intelligence. Actually, it is the intelligence of the pro¬ 
grammer which is remembered by the program and reflected in the pattern of conditional execu¬ 
tion. 

Consider a chemistry lab application as an example. There would be little use for a computer whose 
only function was to turn on a valve when a technician pressed the “START” button. The techni¬ 
cian might just as well turn the valve himself. However, if the computer turned on a valve when the 
“START” was pressed and turned off the valve when a specified pH level occurred, then it is 
performing a much more useful task. If the example is extended to include state-of-the-art remote- 
control valves and electronic pH measuring devices, the computer is now significantly out¬ 
performing the technician. In this example, (in spite of any fancy instrumentation) the quality that 
moved the computer from “useless” to “useful” was its ability to decide when to turn off the valve. 
It was the programmer (you) who actually specified the criteria for the decision. Those criteria were 
then communicated to the computer using conditional-execution program structures. As a result, 
the computer was able to repeat the programmer’s intention with much greater speed and accuracy 
than a human. 

This section presents the conditional-execution statements according to various applications. The 
following is a summary of these groupings. 

1. Conditional execution of one segment. 

2. Conditionally choosing one of two segments. 

3. Conditionally choosing one of many segments. 

Conditional Execution of One Segment 

The basic decision to execute or not execute a program segment is made by the IF...THEN 
statement. This statement includes a numeric expression that is evaluated as being either true or 
false. If true (non-zero), the conditional segment is executed. If false (zero), the conditional segment 
is bypassed. Although the expression contained in an IF...THEN is treated as a Boolean expression, 
note that there is no “BOOLEAN” data type. Any valid numeric expression is allowed. 

The conditional segment can be either a single BASIC statement or a program segment containing 
any number of statements. The first example shows conditional execution of a single BASIC 
statement. 

100 IF P h > 7.7 THEN OUTPUT Value USING 

Notice the test (Ph>7.7) and the conditional statement (OUTPUT Value...) which appear on 
either side of the keyword THEN. When the computer executes this program line, it evaluates the 
expression Ph >7.7. If the value contained in the variable Ph is 7.7 or less, the expression evaluates 
to 0 (false), and the line is exited. If the value contained in the variable Ph is greater than 7.7, the 
expression evaluates as 1 (true), and the OUTPUT statement is executed. If you don’t already 
understand logical and relational operators, refer to Chapter 4 (numbers) or Chapter 5 (strings). 
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By the way, the image specifier # > B causes the output of a single byte. In the example, the value for 
that byte is specified as zero (all bits cleared). Presumably, this turns off all devices connected to a 
GPIO interface. That interface is specified by the value contained in the device selector Va 1 v e. It is 
beyond the scope of this manual to explain the details of controlling valves and instruments. If you 
want to do this kind of control, refer to the BASIC Interfacing Techniques manual and study the 
appropriate Interface Installation manual. 

The same variable is allowed on both sides of an IF...THEN statement. For example, the following 
statement could be used to keep a user-supplied value within bounds. 

IF Number>9 THEN Number=9 

When the computer executes this statement, it checks the initial value of Number. If the variable 
contains a value less than or equal to nine, that value is left unchanged, and the statement is exited. 
If the value of Numb e r is greater than nine, the conditional assignment is performed, replacing the 
original value in Numb e r with the value nine. 

Prohibited Statements 

Certain statements are not allowed as the conditional statement in a single-line IF...THEN. The 
disallowed statements are used for various purposes, but the “common denominator” is that the 
computer needs to find them during prerun as the first keyword on a line. (A possible exception to 
this reasoning is REM, which is not allowed because it makes no sense to allow it. Comments 
certainly aren’t executed conditionally. If comments are necessary on an IF...THEN line, the 
exclamation point can be used.) The following statements are not allowed in a single-line 
IF...THEN. 

Keywords used in the declaration of variables: 

COM OPTION BASE 

DIM REAL 

INTEGER 

Keywords that define context boundaries: 

DEF FN FNEND 

SUB SUBEND 

END 

Keywords that define program structures: 


CASE 

FOR 

CASE ELSE 

IF 

ELSE 

LOOP 

END IF 

NEXT 

END LOOP 

REPEAT 

END SELECT 

SELECT 

END WHILE 

UNTIL 

EXIT IF 

WHILE 


Keywords used to identify lines that are literals: 


DATA 

REM 
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Conditional Branching 

Powerful control structures can be developed by using branching statements in an IF...THEN. Here 
are some examples. 

110 IF Free_space<100 THEN GOSUB Expand-file 
120 ! The line after is always executed 

This statement checks the value of a variable called Free.space, and executes a file-expansion 
subroutine if the value tested is not large enough. The same technique can be used with a CALL 
statement to invoke a subprogram conditionally. One important feature of this structure is that the 
program flow is essentially linear, except for the conditional “side trip” to a subroutine and back. 
This is illustrated in the following drawing. 


1000 

1010 

1020 

1030 

1040 


PRINT Area?"square in*" 

Cent=Area*G*451G 

PRINT Centi"square cm" 

PRINT 

RETURN 


P_flag = 1 P_flag = 0 



2 

= PI * R ■" 2 

_ f1 a 3 THEN G0SUB 1000 

h=Width+l 

th=Len$th+l 


The conditional GOTO is such a commonly used technique that the computer allows a special case 
of syntax to specify it. Assuming that line number 200 is labeled “Start”, the following statements 
will all cause a branch to line 200 if X is equal to 3. 

IF X=3 THEN GOTO 200 

IF X=3 THEN GOTO Start 

IF X=3 THEN 200 

IF X = 3 THEN Start 

When a line number or line label is specified immediately after THEN, the computer assumes a 
GOTO statement for that line. (This improves the readability of programs, because phrases like 
“then start” sound more like English and less like computer jargon.) If execution is redirected by a 
conditional GOTO (implied or expressed), the program flow does not automatically return to the 
line following the IF...THEN. Thus, a conditional GOTO acts like a switch on a railroad track. This is 
illustrated in the following drawing. 


1100 

1110 

1120 

1130 

1140 


Record: ! File 

! Test for open file = 1 

! Do any CREATE t ASSIGN * etc* 
OUTPUT ©File »Text$ 

! Continue with file operation - 



550 Send.text: ! 

5G0 IF File THEN Record 
570 PRINT Tex t$ 

580 Lines=Lines+l 

590 ! Continue with p rintin 3 






54 Program Structure and Flow 


Multiple-Line Conditional Segments 

If the conditional program segment requires more than one statement, a slightly different structure 
is used. Let’s expand the valve-control example. 


100 

IF Ph >7 ♦ 7 

THEN 



110 

OUTPUT 0 

a 1 u e 

USING 

" # f B " ; 0 

120 

PRINT "F 

i n a 1 

Ph =" 

5 Ph 

130 

G0SUB Ne 

x t -1 u b e 


1 40 

END IF 




150 

! Program 

coni 

: i n u e s 

here 


Any number of program lines can be placed between a THEN and an END IF statement. In 
executing this example, the computer evaluates the expression Ph>7.7 in the IF...THEN state¬ 
ment. If the result is false, the program counter is set to 150, and execution resumes with the line 
following the END IF statement. If the condition is true, the program counter is set to 110, and the 
three conditional statements (lines 110, 120, 130) are executed. Program flow then picks up at line 
150, because the END IF is only used during prerun. 

When using multiple-line IF...THEN structures, remember to mark the end of the structure with an 
END IF statement and don’t put any of the statements on the same line as the IF...THEN. If the 
beginning and end of the structure are not properly marked, the computer reports error 347 during 
prerun. 

The conditional segment can contain any statement except one which is use to set context bound¬ 
aries (such as END or DEF FN). In the previous example, the GO SUB Next-tube could have 
been aGOTO Next-tube. In that case, program execution does not pass through 150 when the 
condition is true. A false condition would cause a branch to line 150, while a true condition would 
send execution from line 100, to 110, to 120, to 130, and then to the line labeled “Next_tube”. 

If structuring statements are used within a multiple-line IF...THEN, the entire structure must be 
contained in one conditional segment. This is called nested constructs. The following example 
shows some properly nested constructs. Notice that the use of indenting improves the readability of 
the code. 

1000 IF FI a 3 THEN 

1010 IF End_of_pa3e THEN 

1020 FOR 1=1 TO Skip.length 

1030 PRINT 

1040 Lines=Lines+l 

1050 NEXT I 

10G0 END IF 

1070 END IF 

Choosing One of Two Segments 

Often you want a program flow that passes through only one of two paths depending upon a 
condition. This type of decision is represented pictorally by the following diagram. If you have ever 
been forced to program this type of structure using only the conditional GOTO, you know that the 
result is much more confusing than it needs to be. 
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Flag = 1 


Flag = 0 


400 

IF Fla* THEN 

410 

R = R + 2 

■J 420 

A re a = PI*R“2 

430 

ELSE 

440 

Width=Width+l 

450 

Len*th=Len*th+l 

4 GO 

Area=Width*Len*th 

470 

END IF 

+ 480 

PRINT "Area =" ?Area 

X 480 

! Program continues 



This language has an IF...THEN...ELSE structrure which makes the one-of-two choice easy and 
readable. The following example looks at a device selector which may or may not contain a primary 
address. The variable I s c is needed later in the program and must be only an interface select code. 
If the operator-supplied device selector is greater than 31, the interface select code is extracted from 
it. If it is equal to or less than 31, it already is an interface select code. (This example assumes that 
no secondary addressing is used.) 

500 IF Select>31 THEN 
510 Is c =Se1e c t DIO 100 
520 ELSE 
530 Isc=Select 
540 END IF 

Notice that this structure is similar to the multiple-line IF...THEN shown previously. The only 
difference is the addition of the keyword ELSE. Like the previous example, the structure is termin¬ 
ated by END IF, and the proper nesting of other structures is allowed. The next example shows a 
program segment that removes certain “escape sequences” from a string. The number of bytes in 
the escape sequence varies, but can be determined by inspecting the characters following the 
escape code. Notice the nesting of structures and the conditional branch. When no more escape 
sequences remain in the string, program execution continues atNext_seq. 


3800 Escape: ! 

3810 Point = P0S(A$ >Es c$) 

3820 IF NOT Point THEN Next.seS 
3830 IF A$[Poirit + l 51]<>"6:" THEN 
3840 A$[Point3=A$CPoint+2] 

3850 ELSE 

3880 IF A$[Point+2 51] = "d" THEN 

3870 A$[Point 3 = A$C Point + 43 

3880 ELSE 

3830 A$CPaint3=A$[Point+53 

3800 END IF 

3310 END IF 

3920 GOTO Escape 

3830 ! 

3940 Next_seS: 


! 2-byte sequence 

! 4-byte sequence 

! 5-byte sequence 

! L o o k for more 
! Program continues here 
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Choosing One of Many Segments 

Using SELECT Constructs 

Consider as an example the processing of readings from a voltmeter. In this example, we assume 
that the reading has already been entered, and it contained a function code. These hypothetical 
function codes identify the type of reading and are shown in the following table. 


Function Code 

Type of Reading 

DV 

DC Volts 

AV 

AC Volts 

DI 

DC Current 

AI 

AC Current 

OM 

Ohms 


The first example shows the use of the SELECT construct. The function code is contained in the 
variable Funct$. For the sake of simplicity, the example does not show any actual processing. 
Comments are used to identify the location of the processing segments. The rules about illegal 
statements and proper nesting are the same as those discussed previously in the IF...THEN section. 


2000 

GELECT F ur. ct $ 



2010 

CASE "DO" 



2020 

! 



2030 

! Processing 

for 

DC Uolts 

2040 

j 



2050 

CASE "AO" 



2 0 G 0 

j 



2070 

! Processing 

for 

AC Volts 

2080 

1 



2090 

CASE "DI" 



2100 

! 



2110 

! Processing 

for 

DC Amps 

2120 

! 



2130 

CASE "AI" 



2140 

j 



2150 

! Processing 

for 

AC Amps 

21 GO 

j 



2170 

CASE "OM" 



2180 

| 



2190 

! Processing 

for 

Ohms 

2200 

j 



2210 

CASE ELSE 



2220 

BEEP 



2230 

PRINT “INVALID READING" 

2240 

END SELECT 



2250 

! Program execution 

conti n u e s 
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Notice that the SELECT construct starts with a SELECT statement specifying the variable to be 
tested and ends with an END SELECT statement. The anticipated values are placed in CASE 
statements. Although this example shows a string tested against simple literals, the SELECT state¬ 
ment works for numeric or string variables or expressions. The CASE statements can contain 
constants, variables, expressions, comparison operators, or a range specification. The anticipated 
values, or match items, must be of the same type (numeric or string) as the tested variable. 

The CASE ELSE statement is optional. It defines a program segment that is executed if the tested 
variable does not match any of the cases. If CASE ELSE is not included and no match is found, 
program execution simply continues with the line following END SELECT. 

The following example shows a numeric variable tested with comparison operators and a range 
specifier. 

1500 SELECT Ds 

1510 CASE <1 

1520 ! Processing for inoalid deoice selector 

1530 CASE 1 TO 31 

1540 ! Processing for interface select code 

1550 CASE >31 

1560 ! Contains primary address 

1570 END SELECT 

A CASE statement can also specify multiple matches by separating them with commas, as shown 
below. 

CASE -1 »1*3 TO 7 *>15 

The following CASE statement shows the use of a string expression, rather than a simple constant. 
CASE CHR$(27)& : " )@"&:Eol$ 

You should be aware that if an error occurs when the computer tries to evaluate an expression in a 
CASE statement, the error is reported for the line containing the SELECT statement. This is a result 
of the nature of SELECT constructs and is not a bug. However, it can make things a bit confusing if 
you aren’t aware of it. An error message pointing to a SELECT statement actually means that there 
was an error in that line or in one of the CASE statements. It requires more “detective work” on 
your part to locate the line which actually contains the erroneous expression. 

Using the ON Statement 

This type of program flow can also be generated with the ON statement and some additional 
processing. Let’s do a string example first, using the previous voltmeter example. All the anticipated 
values are placed in a simple string. This string is then searched using the POS function. The results 
of the POS function are adjusted to become consecutive integers beginning with one. This result 
can then be used in the ON statement. 

100 Match$="D0AMDIAI0M" 


500 Pointer=P0S(Match$ >Furi c t $ ) 

510 Pointer=INT((Pointer-l)/2+l) 

520 ON Pointer+1 G0SUB Case_e1se>Case_du>Case_au > 
Case_di > C a s e _ a i > C a 5 e _ o m 
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Notice that a match can only cause values of 1, 3, 5, 7, or 9 from the POS function. A “match not 
found” gives a value of 0. Line 510 converts these to consecutive integers from 0 thru 5. The 
Pointer + 1 expression in line 520 shifts the values to a range 1 thru 6, which is acceptable to the 
ON statement. 

The values of the match characters will determine the “pre-processing” necessary. If you are trying 
to match single bytes, simply adding one to the results of the POS is all that is necessary. Finding 
3-letter sequences requires a line like 510, only with a division by 3. Note also that, except for single 
bytes, this method may not always work. For example, if the current ranges had been indicated by 
DA and AA (instead of DI and AI), Match$ would be “DVAVDAAAOM”. A subsequent search for 
“AA” would return 6 instead of 7 — not good. In a case like that, there are two choices. One 
approach is to rearrange the string being searched; “DVAVDAOMAA” would work. Perhaps the 
items in the string could be separated with a “pad” character and the calculation adjusted accor¬ 
dingly. The other approach is to make each match value a separate element of a string array. The 
array could then be “searched” with a FOR...NEXT loop. This approach works well to resolve 
conflicts, especially with long match strings. However, the extra code lines and array accesses slow 
the process down significantly. 

The ON statement can also be used for numeric values. If the numeric values you are trying to 
match just happen to be consecutive integers starting with one, the variable to be tested can be 
used in the ON statement. However, programmers don’t usually get that lucky. To match arbitrary 
values, the following trick can be used. This example tests the three cases: <0, 1, and >1. 

700 Pointe r = 1 *(X<0)+2*<X = 1)+3*(X>l) 

710 ON Pointer G0SUB Nesatiue>0ne>Greater 

Assuming that you use non-overlapping comparison tests, only one of the values in parentheses will 
be true. The system returns a value of “1” for true. This is multiplied times the corresponding factor 
to give the final value to Pointer. All the other factors drop out because their comparison result is 
zero. Programmers who like strong type checking may raise an eyebrow at this technique, but it 
works. 

Another way of testing for numbers that are integers between 0 and 255 is to use the CHR$ 
function to create string bytes and apply the POS function as explained previously. 
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Repetition 

Humans usually prefer tasks with variety that avoid tedious repetition. A computer does not have 
this shortcoming. You have four structures available for creating repetition. The FOR...NEXT 
structure is used for repeating a program segment a predetermined number of times. Two other 
structures (REPEAT...UNTIL and WHILE) are used for repeating a program segment indefinitely, 
waiting for a specified condition to occur. The LOOP...EXIT IF structure is used to create an 
iterative structure that allows multiple exit points at arbitrary locations. 

The FOR...NEXT structure is used for repeating a program segment a predetermined number of 
times. Two other structures (REPEAT...UNTIL and WHILE) are used for repeating a program 
segment indefinitely, waiting for a specified condition to occur. The LOOP...EXIT IF structure is 
used to create an iterative structure that allows multiple exit points at arbitrary locations. 

Fixed Number of Iterations 

The general concept of repetitive program flow can be shown with the FOR...NEXT structure. With 
this structure, a program segment is executed a predetermined number of times. The FOR state¬ 
ment marks the beginning of the repeated segment and establishes the number of repetitions. The 
NEXT statement marks the end of the repeated segment. This structure uses a numeric variable as a 
loop counter. This variable is available for use within the loop, if desired. The following drawing 
shows the basic elements of a FOR...NEXT loop. 


STARTING 

VALUE 




LOOP 

FINAL 

STEP 



COUNTER 

VALUE 

SIZE 



, * > r- 




200 

FOR Count = 10 TO 0 STEP 

-1 


'210 

BEEP 



REPEATED 

220 

PRINT Count 


SEGMENT 

230 

WAIT 1 




240 

NEXT Count 




The number of loop iterations is determined by the FOR statement. This statement identifies the 
loop counter, assigns a starting value to it, specifies the desired final value, and determines the step 
size that will be used to take the loop counter from the starting value to the final value. When the 
loop counter is an INTEGER, the number of iterations can be predicted using the following formula: 

Step Size + Final Value - Starting Value 
Step Size 

Note that the formula applies to the values in the variables, not necessarily the numbers in the 
program source. For example, if you use an INTEGER loop counter and specify a step size of 0.7, 
the value will be rounded to one. Therefore, 1 should be used in the formula, not 0.7. 
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The loop counter can be a REAL number, with REAL quantities for the step size, starting, or final 
values. In some cases, using REAL numbers will cause the number of iterations to be off by one 
from the preceding formula. This is because the NEXT statement performs an “increment and 
compare”, and there is a slight inaccuracy in the comparison of REAL numbers. If you are 
interested, this is discussed in the next chapter. However, there is no “clean” way around it with 
FOR...NEXT loops. Here is an example: 

200 Count = 0 
210 FOR X=10 TO 20 
220 Count=Count+l 

230 PRINT Count 

240 NEXT X 

According to the formula, this loop should execute 11 times: INT((1 +20-10)/1 = 11). The result 
on the CRT confirms this when the loop is executed. If line 210 is changed to: 

210 FOR X=1 TO 2 STEP .1 

the formula still yields 11 as the number of iterations. However, executing the loop produces only 
10 repetitions. This is because of a very, very small accumulated error that results from the 
successive addition of one-tenth. The error is less significant than the 15th digit, but discernable to 
the computer. In this case, rounding cannot be performed at a time that would help. When you find 
yourself in this situation, one solution is to add a slight adjustment factor to the final value. One half 
of the step size is a convenient adjustment factor. The following line does give the 11 iterations 
predicted by the formula. 

210 FOR X=1 TO 2.05 STEP .1 

Remembering the “increment and compare” operation at the bottom of the loop is helpful. After 
the loop counter is updated, it is compared to the final value established by the FOR statement. If 
the loop counter has passed the specified final value, the loop is exited. If it has not passed the 
specified final value, the loop is repeated. The loop counter retains its exit value after the loop is 
finished. This is not necessarily one full step past the final value. For example: 

FOR 1=1 TO 9.0 

This statement establishes a loop that executes nine times (the default step size is one). The variable 
I has the value 10 when the loop is exited. 

FOR Count =12 TO 1 STEP -0.3 

This statement establishes a loop that executes 37 times. The variable Count has the value .9 when 
the loop is exited. Notice that negative step sizes are allowed using the same keywords as positive 
step sizes. 

The final points to mention concern the execution of the FOR statement. If any variables are 
present to the right of the equal sign, the value used is the value they have when the FOR statement 
is executed. Remember that the FOR statement is only executed once before the loop begins. Also, 
if the number of iterations evaluates to zero or less, the loop is not executed and program execution 
goes immediately to the line following the NEXT statement. Here are some examples. 
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400 FOR 11em = First TO Last 
410 GOSUB Process 

4Z0 Last=Last+l 

430 NEXT Item 

440 ! Execution continues here 

This loop would not be executed if Last were less than First. This is almost always desirable, since it 
prevents the subroutine Process from being invoked with a null item. Also notice that the number of 
iterations is fixed at loop entry when line 400 is executed. That number of iterations does not 
change when the value of Last is changed. 

FOR Item=Item+l TO Last 

The variable Item is used as the loop counter. It receives a starting value that is one greater than the 
value it had when this line is executed. 

Conditional Number of Iterations 

The FOR...NEXT loop produces a fixed number of iterations, established by the FOR statement 
before the loop is executed. Some applications need a loop that is executed until a certain condition 
is true, without specifically stating the number of iterations involved. Consider a very simple 
example. The following segment asks the operator to input a positive number. Presumably, nega¬ 
tive numbers are not acceptable. A looping structure is used to repeat the entry operation if an 
improper value is given. Notice that it is not important how many times the loop is executed. If it 
only takes once, that is just fine. If the poor operator takes ten tries before he realizes what the 
computer is asking for, so be it. What is important is that a specific condition is met. In this 
example, the condition is that a value be non-negative. As soon as that condition has been satisfied, 
the loop is exited. 

800 REPEAT 

BIO INPUT "Enter a positive number 11 (Number 
820 UNTIL Numbe r> = 0 

i 

A typical use of this is an iterative problem involving non-linear increments. One example is musical 
notes. Performing the same operation on all the notes in a 3-octave band is a repetitive process, but 
not a linear one. Musical notes are related geometrically by the 12th root of two. The following 
example simply prints the frequencies involved, but your application could involve any number of 
operations. 

1200 Note=110 ! Start at low A 

1210 REPEAT 

1220 PRINT Note ! 

1230 Note=Note*2 A (1/12) 

1240 UNTIL Note >880 ! End at hish A 

For this example, a FOR...NEXT loop might have been used, with the loop counter appearing in an 
exponent. That would work because it is relatively easy to know how many notes there are in three 
octaves of the musical scale. However, the REPEAT...UNTIL structure is more flexible than 
FOR...NEXT when working with exponential data in general. Examples often occur in the area of 
graphics. The following segment could be used to plot audio frequency data, where the x-axis is 
logrithmic. 
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1500 F r e<=i = 20 

1510 MOVE LOG(Freq) »FNFunc t i on < F re<0 
1520 REPEAT 

1530 DRAW LOG<Freq) »FNFunction(Freq) 

1540 Frei = Freq* 1.2 
1550 UNTIL F req >20000 

The flexibility of this structure is in line 1540. By increasing the frequency with a factor of 1.2, a very 
fast but rough graph is generated. (You need the GRAPH BIN to run this example.) This lets you 
place axes, labels, markers, etc. where you want them without waiting for a time-consuming plot for 
each cosmetic change. Once you have the desired appearance, you could change line 1540 to 
Freq = Freq*1.01. This would greatly increase the resolution of the plot (and reduce its speed). 
To take it one step further, you could make the “resolution factor” a variable and input its value at 
the start of the program. That would make it easy to try many different increments to achieve the 
best compromise between resolution and smoothness. Attempting a similar technique with 
FOR...NEXT loops would involve many extra (and unnecessary) calculations. 

The WHILE loop is used for the same purpose as the REPEAT loop. The only difference between 
the two is the location of the test for exiting the loop. The REPEAT loop has its test at the bottom. 
This means that the loop is always executed at least once, regardless of the value of the condition. 
The WHILE loop has its test at the top. Therefore, it is possible for the loop to be skipped entirely (if 
the conditions so dictate). The following segment shows the same plotting example using a WHILE 
loop. 

1500 F req = 20 

1510 MOVE LOG(Freq)>FNFunction(Freq) 

1520 WHILE Freq<=20000 

1530 DRAW L0G(Fre«O »FNFun c t i on < F re«0 
1540 F re<=i = F r ei* 1.2 
1550 END WHILE 

The next segment shows the use of conditional branching to simulate a REPEAT...UNTIL structure. 
1500 F req = 20 

1510 MOVE LOG(Freq) *FNFunction<Frei) 

1520 Loop.top: ! 

1530 DRAW LOG ( F re=i) »FNFunc t i on ( F rep ) 

1540 Frep=Frep*1.2 

1550 IF F req< =20000 THEN Loop.top 

The WHILE structure can also be simulated using GOTO statements. The following segment shows 
this technique. 

1500 Fre , =i = 20 

1510 MOVE LOG(Freq)#FNFunction<Freq) 

1520 Loop-topi ! 

1530 IF F r e<=i >20000 THEN Loop.exit 
1540 DRAW LOG(Frei) #FNFunction(Freq) 

1550 Freq = Fre«i#l*2 

15G0 GOTO Loop_top 
1570 Loop-exit; ! 
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The REPEAT...UNTIL and WHILE structures are especially useful for tasks that are impossible with 
a FOR...NEXT loop. One such situation is a loop where both the loop counter and the final value 
are changing. Consider the example of stripping all control characters from a string. This can’t be 
done in a loop that starts FOR 1 = 1 TO LEN ( A$ >, because the length of A$ changes each time a 
character is deleted. Therefore, the loop counter used as a subscript will eventually exceed the 
length of the string by more than one, generating an error. The WHILE loop does not have this 
problem. Note that the test at the top of the loop prevents the subscripting from being attempted on 
a null string. This is necessary to avoid an error. 

BOO 1=1 

BIO WHILE I< =LEN(A$ > 

B20 IF A$CI51]<CHR$(32) THEN 

B30 A$CI]=A$C1+1] 

B40 ELSE 

650 1=1+1 

BBO END IF 
B70 END WHILE 

Arbitrary Exit Points 

A pass through any of the loop structures discussed so far included the entire program segment 
between the top and the bottom of the loop. There are times when this is not the desired program 
flow. The LOOP structure defines a repeated program segment and allows any number of con¬ 
ditional exits points in that segment. 

For the first example, consider a search and replace operation on string data. In this example, the 
“shift out” control character is being used to initiate underlining on a printer that understands 
standard escape sequences. The “shift in” control character is used to turn off the underline mode. 
(There is nothing significant about this choice of characters. Any combination of characters could 
serve the same purpose.) 

One approach is to use a loop to search every character in every string to see if it is one of the 
special characters. There are two problems with this method. First, it is a little cumbersome when 
the replacement string is a different length than the target string. Second, it is slow. Admittedly, 
speed it not a significant consideration when driving common mechanical printers. But the destina¬ 
tion might eventually be a lazer printer or mass storage file, making the program’s speed more 
visible. 

A better approach is to use the POS function to locate the target string. Since this function locates 
only the first occurrence of a pattern, it must be placed in a loop to insure that multiple occurrences 
will be found. The LOOP structure is well suited to this task, as shown in the following example. 
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2000 

2010 

2020 

2030 

2040 

2050 

20G0 

2070 

2080 

2090 

2100 

2110 


LOOP 

Posit ion = P0S(A$ »CHR$< 14) ) 

EXIT IF NOT Position 

A$[Positiori]=CHR$(27)6:"6:dD"&:A$[Position + l ] 
END LOOP 
! 

LOOP 

Position = POS(A$»CHR$(15)) 

EXIT IF NOT Position 

A$ C Po sition]= CHR$(27)&"&d@&A$[Po sition +13 
END LOOP 

! Last EXIT sfoes to here 


In this segment, all occurrences of “shift out” are replaced by “escape &dD” to enable underline 
mode. All occurrences of “shift in” are replaced by “escape &d@” to disable underlining. Notice 
that there is no problem replacing one character with four (assuming that A$ is large enough). Lines 
containing no special characters are processed by only two POS functions, which is much faster and 
cleaner than performing two comparisons for every character in every line. 

Another common use for this structure is the processing of operator input. Recall the RE¬ 
PEAT... UNTIL example that tested for the input of a positive number. Although this structure kept 
the computer happy, it left the operator in the dark. The LOOP structure provides for the additional 
processing needed, as shown in the following example. 


200 

LOOP 


210 

INPUT 

"Enter a positive number♦"tNumber 

220 

EXIT IF 

N u m b e r > = 0 

230 

BEEP 


240 

PRINT 


250 

PRINT 

"Negative numbers are not allowed*" 

2 GO 

PRINT 

"Repeat entry with a positive number* 

270 

END LOOP 



Another point to remember is that the LOOP structure permits more than one exit point. This 
allows loops that are exited on a “whichever comes first” basis. Also, the EXIT IF statement can be 
at the top or bottom of the loop. This means that the LOOP structure can serve the same purposes 
as REPEAT...UNTIL and WHILE, if that suits your programming style. 




Program Structure and Flow 65 


The EXIT IF statement must appear at the same nesting level as the LOOP statement for a given 
loop. This requirement is best shown with an example. In the “WRONG” example, the EXIT IF 
statement has been nested one level deeper than the LOOP statement because it was placed in an 
IF...THEN structure. 

WRONG 


GOO 

LOOP 

G10 

Te s t = RND-♦5 

620 

IF TestCO THEN 

630 

G05UB Negative 

640 

EL5E 

650 

EXIT IF Tes t >♦ 

660 

G05UB Positive 

670 

END IF 

680 

END LOOP 

RIGHT 

B00 

LOOP 

G10 

Te s t = RND-.5 

620 

EXIT IF Te s t > • 4 

S30 

IF TestCO THEN 

640 

GOSUB Negative 

650 

ELSE 

660 

GOSUB Positive 

670 

END IF 

680 

END LOOP 
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Event-Initiated Branching 

Your computer has a special kind of program flow that provides some very powerful tools. This 
tool, called event-initiated branching, uses interrupts to redirect program flow. The process can be 
visualized as a special case of selection. Everytime program flow leaves a line, the computer 
executes an “event-checking” routine. This is set of machine-language “if...then” statements 
concerning interrupts. If an event is enabled and “true”, this “event-checking” routine causes the 
program to branch. 

The process of “event checking” is represented in the following lines. Notice that it is possible for 
event-initiated branching to occur at the end of any program line, which includes the lines of a 
subprogram. This can give the appearance of “middle-of-line” branching when it occurs during a 
user-defined function, subprogram. These potential branching points are marked by the words 
“gosub event_check”. This does not refer to a BASIC subroutine, but is just a symbolic reminder of 
where event-initiated branching can occur. If the operating system finds a “true” event, a branch is 
taken. If not, program execution resumes with the “normal” program flow. 

10 PRINT X( gosub event_check) 

20 X = X +1 (gosub event_check) 

30 GOTO 10 (gosub event_check) 

Enabling Events 

Event-initiated branching is established by the ON-event statements. Here is a list of the statements 
that fall in this category: 

ON END ON ERROR 

ON KBD ON KEY 

ON KNOB ON INTR 

ON TIMEOUT ON SIGNAL 

The ON END event is used to detect when the end of a mass storage file is reached. This is 
discussed in Chapter 7. 

The ON CYCLE, ON DELAY and ON TIME statements are used to direct program flow using the 
clock. They are discussed in Chapter 9. 

The ON ERROR event is used to trap run-time errors and provide for error-recovery routines. This 
is discussed in Chapter 11. 

The ON KBD, ON KEY, and ON KNOB events pertain to various parts of the keyboard and are 
used to enhance the “human interface” of programs. ON KBD lets you re-define the entire 
keyboard to suit the needs of your program. This is discussed in the BASIC Interfacing Techniques 
manual. The ON KEY statement is used to define and label the softkeys on the keyboard. The ON 
KNOB statement lets you capture turns of the knob. This chapter has some examples of ON KEY 
and ON KNOB. 

The ON EOR, ON EOT, ON SIGNAL, ON INTR and ON TIMEOUT events pertain to data transfer, 
interfaces and I/O operations. These are discussed in the BASIC Interfacing Techniques manual. 


ON CYCLE ON EOR 

ON DELAY ON EOT 

ON TIME 
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The best way to understand how event-initiated branches operate in a program is to sit down at the 
computer and try a few examples. Start by entering the following short program. 

110 ON KEY 1 LABEL "Inc" GOSUB Plus 
120 ON KEY 5 LABEL "Dec" GOSUB Minus 
130 ! 

140 Spin: DISP X 
150 GOTO Spin 
ISO !. 

170 Plus: X = X+1 
180 RETURN 
ISO ! 

200 Minus: X=X-1 
210 RETURN 
220 END 

Notice the various structures in this sample program. The ON KEY statements are executed only 
once at the start of the program. Once defined, these event-initiated branches remain in effect for 
the rest of the program. (Disabling and deactivating are discussed later.) The program segment 
labeled “Spin” is an infinite loop. If it weren’t for interrupts, this program couldn’t do anything 
except display a zero. However, there is an implied IF...THEN at the end of lines 140 and 150 
because of the ON KEY action. This allows a selection process to occur. Either the “Plus” or the 
“Minus” subroutine can be selected as a result of softkey presses. These are normal subroutines 
terminated with a RETURN statement. (In the context of interrupt programming, these subroutines 
are called service routines.) The following section of pseudocode shows what the program flow of 
the “Spin” segment actually looks like to the computer. 

Spin: display X 

if Keyl then gosub Plus 
if Key5 then gosub Minus 
goto Spin 

This pseudocode is an over-simplification of what is actually happening, but it shows that the 
“Spin” segment is not really an infinite loop with no decision-making structure. Actually, most 
programs that use event-initiated branching to control program flow will contain what appears to be 
an infinite loop. That is the easiest way to “keep the computer busy” while it is waiting for an 
interrupt. 

Now run the sample program you just entered. Notice that the bottom of the CRT displays an 
inverse-video label area. These labels are arranged to correspond to the layout of the softkeys. The 
labels are displayed when the softkeys are active and are not displayed when the softkeys are not 
active. Any label which your program has not defined is blank. The label areas are defined in the 
ON KEY statement by using the keyword “LABEL” followed by a string. 

The starting value in the display line is zero, since numeric variables are initialized to zero at prerun. 
Each time you press ( ki ) or ( f\ ) , the displayed value of X is incremented. Each time you press 
( k 5 ) for ( ft ) , the displayed value of X is decremented. This simple demonstration should 
aquaint you with the basic action of the softkeys. 
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It is possible to make structures that are much more elaborate, with assignable priorities for each 
key, and keys that interrupt the service routines of other keys. There are many applications where 
priorites are not of any real significance, such as the example program running now. However, 
priorities will sometimes cause unexpected flow problems. One type of priority problem can be 
shown with a simple modification to our example program. Insert the following line right after line 
170. 

171 GOTO 171 

Now run the program and press ( ki ) or (Ml . Notice that the program “locks up” and all 
subsequent presses of either softkey do nothing. This is not simply because line 171 creates an 
infinite loop. The program segment at “Spin” was a infinite loop and that didn’t bother the softkeys 
at all. The problem is that the priority for the “Plus” service routine is higher than the main program 
priority. None of the softkeys have been assigned a high enough priority to interrupt another service 
routine. A full discussion on interrupt priority can be found in the “Interface Events” chapter of the 
BASIC Interfacing Techniques manual. If you think you have an application that is “priority 
sensitive”, read that section carefully. 

Using the Knob 

One characteristic of interrupt-driven program flow is that the computer’s decisions can be more 
easily synchronized with the actions of devices connected to it. This type of application is often 
called real-time programming. An important example of real-time programming is machine con¬ 
trol. A computer running an automatic packing machine must turn off the flow immediately when 
the jar is full. It is not acceptable for the computer to wait until the inventory printout is done and 
peanut butter is dumped all over the conveyor belt. Although machine control applications are very 
important, their extensive interfacing makes them inconvenient or impossible to use as demonstra¬ 
tion programs in a manual such as this. 

Another common example of real-time programming is computer games. The computer is ex¬ 
pected to respond “instantly” to button presses, lever movement, etc. The operator expects 
immediate correlation between their input and the computer’s output or display. Your BASIC 
Utilities Disc has a couple of simple games on it that demonstate interaction between the CRT, 
softkeys, and knob. Feel free to list any of the programs on that disc if you want further examples of 
various techniques. 

The following program is a very short example that demonstates a real-time interaction between the 
knob and the CRT. If you run this example program and turn the knob, you will see the kind of 
interaction that might be used for cursor control in a text editor. Obviously, a real cursor-control 
routine would be much more sophisticated, but this demonstrates the basic idea. 
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10 ON KNOB .1 GOSUB Moue.blip 

20 Spin: GOTO Spin 

30 ! 

40 Moue_blip: ! 

50 PRINT TABXY(Spotx»Spoty)5" "5 

SO Spo t x =Spo t x+KNOBX/5 

70 S p o t y = S p o t v + K NOBY/5 

80 IF Spoty<1 THEN Spoty=l 

SO IF Spot 1 />18 THEN Spot y = 18 

100 IF SpotxCl THEN Spotx=l 

110 IF Spo t x >50 THEN Spotx = 50 

120 PRINT TABXYtSpotx»Spoty) !CHR$(127) 5 

130 RETURN 

140 END 

This example uses a short infinite loop to wait for pulses from the knob (line 20). Interrupts from the 
knob are enabled by the ON KNOB statement in line 10. The service routine erases the old “blip”, 
performs some scaling and range checking on the knob input, and prints the new “blip”. 

The scaling and range checking are very important in this kind of interactive routine. Humans 
expect their interface to have a certain “feel”. Displays should not change too quickly or too slowly. 
Certain kinds of displays are expected to change logarithmically, others are expected to change 
linearly. The boundary values of variables are expected to conform to the boundaries of the 
display. To initiate yourself to some of these concepts, try modifying this simple example. Remove 
one or more of the range checking lines. (An easy way to do this kind of editing is to place an 
exclamation point in front of the statement. This turns it into a comment, removing it from the flow 
of execution. But it can be easily returned to the program by deleting the exclamation point.) Also 
try changing the scaling factor in lines 60 and 70. Notice the “feel” that results from larger and 
smaller increments, or even logarithmic scaling. 

Deactivating Events 

Knowing how to “turn off’ the interrupt mechanism is just as important as knowing how to enable 
it. Often, an event is a desired input during one part of the program, but not during another. You 
might use softkeys to set certain process parameters the start of a program, but you don’t want 
interrupts from those keys once the process starts. For example, a report generating program could 
use a softkey to select single or double spacing. This key should be disabled once the printout starts 
so that an accidental keypress does not cause the computer to abort the printout and return to the 
questions at the beginning of the program. On the other hand, you might want an “Abort” key that 
does precisely that. The important thing is that you decide on the desired action and make the 
computer obey your wishes. 

Before going any further, let’s explain some important terminology. There are two general methods 
for “turning off’ an interrupt. If an interrupt source is deactivated, it no longer has any influence on 
program flow. You can press a deactivated key all day long and nothing will happen. However, if 
an event is disabled, its action has only been temporarily postponed. The computer remembers 
that a key was pressed while it was disabled, and the action for that key will occur at the earliest 
opportunity once the disabled state is removed. There are examples in this section to demonstate 
the difference betweem these two conditions. 
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All the “ON-event” statements have a corresponding “OFF-event” statement. This is one way to 
deactivate an interrupt source. 

• OFF KEY deactivates interrupts from the softkeys. If a softkey is pressed while deactivated, it 
does nothing. 

• OFF KNOB deactivates the ON KNOB interrupts. Turning the knob while ON KNOB is 
deactivated causes normal scrolling on the CRT. 


The following example shows one use of OFF KEY to disable the softkeys. (Note that ( k n ) is 
used in the description. If you have an HP 46020A keyboard, just substi tue ( /n ) .) A softkey is 
used to select a parameter for a small printing routine. Each press of ( ki ] increments and displays 
the step size that will be used as an interval between the printed numbers. When the desired step 
size has been selected, ( k4 ) is pressed to start the printout. Enter and run this example. Notice 
that with line 240 and 250 commented out, the softkey menu, or label area, never changes. 


100 Begins ! 

110 ON KEY 1 LABEL " DELTA 
120 ON KEY 4 LABEL " START 
130 Inc=1 

140 DISP "Step Size = 1" 
150 ! 

ISO Spin: GOTO Spin 
170 ! 

180 Step_size: ! 

190 Inc=Inc+l 
200 DISP "Step Size = " 5 Inc 
210 RETURN 
220 ! 

230 Process: ! 

240 ! OFF KEY 

250 ! ON KEY 8 LABEL " ABORT 

280 N u m b e r = 0 

270 FOR 1=1 TO 10 

280 Number=Number+Inc 

290 PRINT Number? 

300 WAIT *8 

310 NEXT I 
320 Leave: ! 

330 OF KEY 8 
340 PRINT 
350 GOTO BeSin 
380 END 


G0SUB Step.size 
GOTO Process 


! Wait for Keypress 


! Change increment 


! Deactivate first choices 
GOTO Leave 


! Deactivate ABORT 
! End line 
! Start over 


Now run the example again and press ( ki ) or ( k4 ) while the printout is in progress. Notice that 
the keys are still active and produce undesired effects on the printing process. To “fix this bug”, 
remove the exclamation point from line 240. This disables all the softkeys when the printing process 
starts. Notice that the softkey menu goes away when no sofkeys are active. This is a very handy 
feature while you are experimenting with interupts. It provides immediated feedback to indicate 
when interrupts are active and when they are not. 

Finally, remove the exclamation point from line 250. Now, the softkey menu appears during the 
printing process. However, the choices are different than at the start of the program. The keys used 
to select the parameter and st art the process are not active, because they are not needed at this 
point in the program. Instead, ( k8 ) can be used to “gracefully” abort the process and return to 
the start of the program. 
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The OFF KEY statement can include a key number to deactivate a selected key. This was done in 
line 330. 

Disabling Events 

All the previous examples have shown complete deactivation of the softkeys. It is also possible to 
temporarily disable an event-initiated branch. This is done when an active event is desired in a 
process, but there is a special section of the program that you don’t want to be interrupted. Since it 
is impossible to predict when an external event will occur, the special section of code can be 
“protected” with a DISABLE statement. This is sometimes necessary to prevent a certain variable 
from being changed in the middle of a calculation or to insure that a interface polling sequence runs 
to completion. It is difficult in a short, simple example to show why you would need to do this. But it 
is not difficult to show how to do it. 

100 ON KEY 9 LABEL " ABORT" GOTO Leave 
110 ! 

120 Print-lines ! 

130 DISABLE 

140 FOR 1=1 TO 10 

150 PRINT 15 

1B0 WAIT .3 

170 NEXT I 

180 PRINT 

190 ENABLE 

200 GOTO Print-line 

210 ! 

220 Leave: END 

This example shows a DISABLE and ENABLE statement used to “frame” the PrintJine segment 
of the program. The “ABORT” key is active during the entire program, but the branch to exit the 
routine will not be taken until an entire line is printed. The operator can press the “ABORT” key at 
any time. The keypress will be logged, or remembered, by the computer. Then when the ENABLE 
statement is executed, the event-initated branch is taken. Enter and run the example to observe this 
method of delaying interrupt servicing. 
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Notes 
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Numeric Computation 


Chapter 

4 


Introduction 

When most people think about computers, the first thing that they think of is number¬ 
crunching, the giant calculator with a brain. Whether this is an accurate impression or not, 
numeric computations are an important part of computer programming. 

Numeric computations deal exclusively with numeric values. Thus, adding two numbers and 
finding a sine or a logarithm are all numeric operations; while converting bases and converting a 
number to a string or a string to a number are not. (Converting bases and converting numbers 
to strings and strings to numbers are covered in the chapter on String Operations.) 

The most fundamental numeric operation is the assignment operation, achieved with the LET 
statement. The LET statement originally required the keyword LET for BASIC interpreters, but 
your computer makes it optional. Thus the following statements are equivalent: 

LET A = A + 1 
A = A + 1 


Numeric Data Types 

There are two numeric data types in BASIC that you are using, INTEGER and REAL. Any numeric 
variable that is not declared an INTEGER is a REAL variable. The valid range for REAL numbers is 
approximately: 

-1.797 073 134 862 315 X 10 308 thru 1.797 073 134 862 315 X 10 308 
the smallest non-zero REAL value allowed is approximately: 

± 2.225 073 858 507 202 X 10- 308 

A REAL can also have the value of zero. 

An INTEGER can have any whole-number value from: 

-32 768 thru +32 767 

Both REAL and INTEGER variables may be grouped into arrays. 







74 Numeric Computation 


Declarations 

It is good programming practice to declare all variables, and both INTEGER and REAL state¬ 
ments are provided for declaring variables: 

INTEGER I. J* Days(5) * WeeKs(5:17) 

REAL X. Y. Moltasre(4)» Hours<5»8:13) 

Each of the above statements declares two scalar and two array variables. A scalar is a variable 
which can, at any given time, represent a single value. An array is a subscripted variable, and 
can contain multiple values, accessed by subscripts. It is posible to specify both the lower and 
upper bounds of an array, or to specify the upper bound only, and use the existing OPTION 
BASE as the lower bound. Details on declarations of arrays and how to use them are provided 
later in this chapter when arrays are dealt with in detail. The DIM statement may also be used to 
declare a REAL array. 

DIM R(4*5) 

An ALLOCATE statement can be used to declare both REAL and INTEGER arrays. 

ALLOCATE REAL Co_ords(2# 1 :Points) * INTEGER Status(1:Points) 

The ALLOCATE statement allows you to dynamically allocate memory in programs which 
need tight control over memory use. 

Type Conversions 

The computer will automatically convert between REAL and INTEGER values in assignment 
statements and when parameters are pased by value in function and subprogram calls. When 
parameters are passed by reference the conversion will not be made and a type mismatch error 
will be reported. Whenever numbers are converted from REAL to INTEGER representations, 
information can be lost. There are two potential problem areas in this conversion, rounding 
errors and range errors. 

The computer will automatically convert between types when an assignment is made, and this 
presents no problem when an INTEGER is converted to a REAL. However, when a REAL is 
converted to an INTEGER, the REAL is rounded to the closest INTEGER value. When this is 
done, all information about the number to the right of the radix (decimal point) is lost. If the 
fractional information is truly not needed, there is no problem, but converting back to a REAL 
will not reconstruct the lost information — it stays lost. 

Another potential problem with REAL to INTEGER conversions is the difference in ranges. 
While REAL values range from approximately - 10 308 to + 10 308 , the INTEGER range is only 
from —32 768 to +32 767 (approximately - 10 4 thru + 10 4 ). Obviously, not all REAL values 
can be rounded into an equivalent INTEGER value. This problem can generate INTEGER 
Overflow errors. 

While the rounding problem is important, it does not generate an execution error. The range 
problem can generate an execution error, and you should protect yourself from crashing the 
program by either testing values before assignments are made, or by using ON ERROR to trap 
the error, and making corrections after the fact. 
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The following fragment shows a method to protect against INTEGER overflow errors: 

200 IF X > 327B7 THEN X= 327G7 
210 IF X < -327G8 THEN X = -327G8 

220 Intx = X 

It is possible to achieve the same effect using MAX and MIN functions: 

200 Y = MAX(MIN(X t 327G7)> -327G8) 

Both these methods limit the excursion, but lose the fact that the values were originally out of 
range. If out-of-range is a meaningful condition, an error handling trap is more appropriate. 

200 IF (-327G8< =X) AND (X<=32767) THEN 
210 Y = X 

220 ELSE 

230 G0SUB 0ut_of_rariSe 

240 END IF 


Internal Numeric Formats 

The storage format for REAL and INTEGER numbers in memory are as follows: 


WORD A WORD A +1 WORD A + 2 WORDA + 3 



mantissa sign exponent - 1023 

1 X 2 X l.n 


Storage Format for REAL Variables 


INTEGER 

(2’s COMPLEMENT) 


15 

0 


















t 

SIGN 


Storage Format for INTEGER Variables 
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Precision and Accuracy: The Machine Limits 

Your computer stores all REAL variables with a sign, approximately 15 significant digits, and 
the exponent value. For most engineering and other applications, rounding errors are not a 
problem because the resolution of the computer is well beyond the limitations of most scientific 
measuring devices. However, when high-resolution numerical analysis requires accuracy 
approaching the limits of the computer, round-off errors must be considered. 

Rounding errors should be considered when conversions are made between decimal digits and 
binary form. Input and output operations are one time when this occurs. Given the format used 
for REALs, the conversion REAL —> decimal —> REAL will yield an identity only if the REAL —* 
decimal conversion produces a 17-decimal-digit mantissa and the calculations for the conver¬ 
sions are done in extra precision. This is not the case on the Series 200. Therefore, several 
things can be said about these conversions on the Series 200 computers: 

• Up to and including 16 decimal digits are allowed when storing a number in internal form. 
If there are more digits, they are ignored. 

• Up to and including 15 decimal digits may be output when converting a REAL for printing, 
display, etc. A full 16-digit conversion is not allowed because there are not 16 full digits of 
precision. 

• It is possible for two distinct decimal numbers to map onto the same REAL number 
because the binary mantisa does not have enough bits to represent all 16 decimal digits. 
This can happen only if the decimal numbers are specified to 16-digits. 

• It is possible for two distinct REAL numbers to convert to the same decimal number even if 
the conversion is done to 15-decimal-digit accuracy. Therefore, you cannot use a compari¬ 
son of the digits in printed or displayed numbers to check for equality. 

• All distinct 15 digit decimal strings have a correct distinct REAL representation, but it is not 
always possible to map them onto their correct representation because REAL multiplies 
are not done in extra precision, and the table entries are only 64 bits. In other words, the 
decimal -» REAL conversion may produce a REAL that differs from the true representa¬ 
tion by a maximum of two bits. 

There are references at the end of this chapter to documents that contain further information on 
the subject of representing real numbers. 
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Evaluating Scalar Expressions 

The Hierarchy 

If you look at the expression 2 + 4/2 + 6, it can be interpreted several ways: 

• 2 +(4/2)+ 6 = 10 

• (2 + 4)/2 + 6 = 9 

• 2+ 4/(2+ 6) = 2.5 

• (2 + 4)/(2 + 6) = .75 

Computers do not deal well with ambiguity, so an arbitrary hierarchy is used for evaluating 
expressions to eliminate any questions about the meaning of an expression. When the compu¬ 
ter encounters a mathematical expression, an expression evaluator is called. If you do not 
understand the expression evaluator, you can easily be surprised by the value returned for a 
given expression. In order to understand the expression evaluator, it is necessary to understand 
the valid elements in an expression and the evaluation hierarchy (the order of evaluation of the 
elements). 

Six items can appear in a numeric expression; operators, constants, variables, intrinsic func¬ 
tions, user-defined functions and parentheses. Operators modify other elements of the express¬ 
ion. Constants and variables represent numeric values in the system. Functions, both intrinsic 
and user-defined, return a value which replaces them in the evaluation of the expression. 
Parentheses are used to modify the evaluation hierarchy. 

The following table defines the hierarchy used by the computer in evaluating numeric expres¬ 
sions. 


Math Hierarchy 


Precedence 

Operator 

Highest 

Parentheses; they may be used to force any order of operation 
Functions, both user-defined and machine-resident 

Exponentiation: " 

Multiplication and division: * / MOD DIO MODULO 

Addition, subtraction, monadic plus and minus: + 

Relational Operators: =<>< >< = > = 

NOT 

AND 

Lowest 

OR EXOR 
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When an expression is being evaluated it is read from left to right and operations are performed 
as encountered, unless a higher precedence operation is encountered immediately to the right 
of the operation encountered, or unless the hierarchy is modified by parenthesis. If the compu¬ 
ter cannot deal immediately with the operation, it is stacked, and the evaluator continues to 
read until it encounters an operation it can perform. It is easier to understand if you see how an 
expression is actually handled. The following expression is complex enough to demonstrate 
most of what goes on in expression evaluation. 

A = 5+3*(4+2)/SIN(X)+X*(l>X)+FNNe*l*(X<5 AND X>0) 


In order to evaluate this expresion, it is necessary to have some historical data. We will assume 
that DEG has been executed, that X= 90, and that FNNegl returns -1. Evaluation proceeds as 
follows: 

5+3* (4+2) /SIN(X)+X*(l>X)+FNNegl*(X<5 AND X>0) 

5+3*G/SIN(X)+X*(1>X)+FNNeSl*(X<5 AND X>0) 

T 

5+18/SIN(X)+X*(1>X)+FNNeSl*(X<5 AND X>G) 

7 ~ 

5+18/l+X*(l>X)+FNNe3l*(X<5 AND X>0) 


7 


5+18+X*(l>X)+FNNe3l*(X<5 AND X>0) 


7 


23+X* (l>X) +FNNegl*(X<5 AND X>0) 
23 +X*Q +FNNe3l*(X<5 AND X>0) 

23 + CH-FNNe3l*(X<5 AND X>0) 


23 + FNNe 91 *(X< 5 AND X>0) 


7 


2 3 + - 1 *(X < 5 AND X>0) 

7 

23+-1 *(0 AND X>0) 

7 

23 + -1*(0 AND 1) 


23+-1*0 


7 


23+0 

7 

23 
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The Delayed Binding Surprise 

The computer delays binding of a variable to its value as long as possible. In the actual 
evaluation, a pointer to the location of a variable is what is stacked. This means that if a variable 
exists in an area of COM accessible to both the main program and a user-defined-function, is 
used in an expression that also calls the user-defined-function, and is modified in the function, 
the value of the expression can be surprising, although not unpredictable. For example, if we 
define a function FNNe 3 1 that returns a minus 1, we would expect the following lines to print 2. 

10 COM X 
20 X = 3 

30 Y = X + FNNe 31 
40 PRINT Y 


However, if the user-defined-function looks like this: 

1000 DEF FNNe e1 
1010 COM X 

1020 X = 500 

1030 RETURN -1 

1040 FN END 


The actual result will be 499. Surprising, but not unpredictable. The same thing will happen if 
the variable is passed by reference and modified in the user-defined-function. This general case 
of occurrences is lumped together under the term side-effects, and should be avoided. There¬ 
fore, don’t use a user-defined-function to modify values of variables. They are designed for 
returning a single value, and are best reserved for that. 


Operators 

There are three types of operators in BASIC, monadic, dyadic, and comparison. 

• A monadic operator performs its operation on the expression immediately to its right. 

+ - NDT 

• A dyadic operator performs its operation on the two values it is between. 

* * / MOD MODULO DIO +-=<><><=>= AND OR EX0R 

• A comparison operator returns a 1 (true) or a zero (false) based on the result of a relational test 
of the operands it separates. The comparison operators are a subset of the dyadic operators 
that are considered to produce boolean results. 

<><=>= = <> 

While the use of most operators is obvious from the descriptions in the language reference, 
some of the operators have uses and side-effects that are not always apparent. 

Expressions, Calls, and Functions 

All numeric expressions are passed by value to subprograms. Thus 5 + X is obviously passed by 
value. Not quite so obviously, + X is also passed by value. The monadic operator makes it an 
expression. 
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Strings in Numeric Expressions 

String expressions can be directly included in numeric expressions if they are separated by 
comparison operators. The comparison operators always yield boolean results, and boolean 
results are numeric values in BASIC. 

Step Functions 

The comparison operators are obviously useful for conditional branching (IF...THEN state¬ 
ments), but are also valuable for creating numeric expressions representing step-functions. For 
example, let’s try to represent the function: 

• IF Select < 0 

Then Result = 0 

• IF0< = Select <1 

Then Result equals the square root of A 2 + B 2 . 

• IF Select > = 1 (any other value) 

Then Result = 15 

It is possible to generate the required response through a series of IF. . .THEN statements, but 
it can also be done with the following expression: 

1210 Result=(Select<0)*0+(Select>=0 AND Select<l)*SQR(A‘2+B A 2)+(Select>l)*15 

While the technique may not please the purist, it actually represents the step function very well. 
The boolean expressions each return a 1 or 0 which is then multiplied by the accompanying 
expression. Expressions not matching the selection return 0, and are not included in the result. 
The value assigned to Select before the expression is evaluated determines the computation 
placed in the result. This technique can be used to represent other functions, but the program 
statement cannot exceed the maximum allowable line length. 

Making Comparisons Work 

If you are comparing INTEGER numbers, no special precautions are necessary. However, if 
you are comparing REAL values, especially those which are the results of calculations and 
functions, it is possible to run into problems due to rounding and other limits inherent in the 
system. For example, consider the use of comparison operators in IF..THEN statments to check 
for equality in any situation resembling the following: 

1220 DEG 

1230 A = 25♦37S5477 

1240 IF SIN(A)-2+C0S(A)"2=1 THEN 

1250 PRINT "Equal" 

12B0 ELBE 

1270 PRINT "Not Equal" 

1280 END IF 


You may find that the equality test fails due to rounding errors or other errors caused by the 
inherent limitations of finite machines. A repeating decimal or irrational number cannot be 
represented exactly in any finite machine. 
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A good example of equality error occurs when multiplying or dividing data values. A product of 
two non-integer values nearly always results in more digits beyond the decimal point than exists 
in either of the two numbers being multiplied. Any tests for equality must consider the exact 
variable value to its greatest resolution. If you cannot guarantee that all digits beyond the 
required resolution are zero, there are three techniques that can be used to eliminate equality 
errors: 

• Use the DROUND function to eliminate unwanted resolution before comparing results. 

• Use the absolute value of the difference between the two values, and test for the difference 
less than a specified limit. 

• Use the absolute value of the relative difference between two values, and test for the 
difference less than a specified limit: 

IF ABS((C-F)/C) < 10'-Delta_powe r THEN PRINT "C is equal to F" 


The following example shows the DROUND technique: 


! Product is 1028.087G3750 


1050 A = 32.5087 

1080 B=31.825 

1070 C=A*B 

1080 D=32.5122 

1080 E = 31.821585508 

1100 F=D*E ! Product is 1028.08783751 

1110 IF C=F THEN 1130 

1120 PRINT "C is not equal to F" 

1130 C = DR0UND(C >7) 

1140 F = DR0UND(F ,7) 

1150 IF C = F THEN 

1160 PRINT "C equals F after DROUND" 

1170 ELSE 

1180 PRINT "C not equal to F after DROUND" 

1180 END IF 

1200 END 


You can experiment with the concept by substituting other values for variables A, B, D, and E, 
and by changing the number of digits specified in the DROUND function. 

Here is an example of the absolute value method of testing equality. In this case, a difference of 
less than 0.001 is assumed to be evidence of adequate equality. Using the previous example, 
we change technique at line 1130. 

1130 IF ABS(C-F)<.001 THEN 

1140 PRINT "C is equal to F within 0.001" 

1150 ELSE 

1180 PRINT "C is not equal to F within 0.001" 

1170 END IF 
1180 END 


This technique has the advantage that no additional statements are invested in overhead while 
preparing the data for evaluation. It also enables you to easily establish tolerance limits in 
making value comparisons, a capability that is useful in production and testing applications. 
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Finally, here is an example of the relative difference method. Once again, we change the 
technique at line 1130. 

1130 IF ABB((C-F)/C)< 10"-3 THEN 

1140 PRINT "Relative difference between C and F less than 10"-3" 

1150 ELSE 

11 GO PRINT "Relative difference between C and F Greater than 10"-3" 

1170 END IF 
1180 END 

Resident Numerical Functions 

The resident functions are the functions that are part of the BASIC language (also called 
intrinsic). Numerous functions are included in the BASIC you are using to make mathematical 
modeling easier. The following functions are available: 


Function 

Description 

ABS 

Returns the absolute value of an expression. 

ACS 

Returns the arccosine of an expression. 

ASN 

Returns the arcsine of an expression. 

ATN 

Returns the arctangent of an expression. 

BASE 

Returns the lower subscript bound of a dimension of an array. (Requires MAT) 

BIN AND 

Returns the bit-by-bit logical-and of two arguments. 

BINCMP 

Returns the bit-by-bit complement of two arguments. 

BINEOR 

Returns the bit-by-bit exclusive-or of two arguments. 

BINIOR 

Returns the bit-by-bit inclusive-or of two arguments. 

BIT 

Returns the state of a bit of the argument. 

COS 

Returns the cosine of the angle represented by the expression. 

CRT 

Returns the INTEGER 1. This is the select code of the internal CRT. 

DATE 

Takes a string expression and returns the number of seconds between midnight on the 
morning of the date represented by the string expression and 24 November -4713. 
(Requires CLOCK) 

DET 

Returns the determinant of a matrix. (Requires MAT) 

DOT 

Returns the inner (dot) product of two vectors. (Requires MAT) 

DROUND 

Rounds a number to a number of digits. 

DVAL 

Returns the whole number value of a binary, octal, decimal, or hexadecimal 32-bit 
integer. The argument is a string. 

EXP 

Raise the Napierian e to an power, e ~ 2.718 281 828 459 05. 

FRACT 

Returns the “fractional” part of the argument. 

INT 

Returns the greatest integer that is less than or equal to an expression. The result is of the 
same type (INTEGER or REAL) as the original number. 

IVAL 

Returns the INTEGER value of a binary, octal, decimal, or hexadecimal 16-bit integer. 
The argument is a string. 

KBD 

Returns the INTEGER 2. This is the select code of the keyboard. 

LGT 

Returns the base 10 logarithm of an expression. 
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Function 

LOG 

MAX 

MAXREAL 

MIN 

MINREAL 

PI 

PROUND 

PRT 


_Description_ 

Returns the natural logarithm (Napierian base e) of an expression. 

Returns the larger of a list of expressions. (Requires MAT) 

Returns the largest REAL number. 

Returns the smaller of a list of expressions. (Requires MAT) 

Returns the smallest REAL number. 

Returns the constant 3.141 592 653 589 79, an approximate value for it. 

Returns the value of the argument rounded to a power of ten. 

Returns the INTEGER 701. This is the default (factory set) device selector for an external 
printer. 


RANK 

RES 

RND 

ROTATE 

SC 

SIN 

SIZE 

SGN 

SHIFT 

SQR 

SUM 

TAN 

TIME 


Returns the number of dimensions in an array. (Requires MAT) 

Returns the last live keyboard numeric result. 

Returns a pseudo-random number that is greater than 0 but less than 1. 

Returns a value obtained by shifting an INTEGER representation of an argument a 
specific number of bit positions, with wraparound. 

Returns the interface select code associated with an I/O path name. 

Returns the sine of the angle represented by an expression. 

Returns the number of elements in a dimension of an array. (Requires MAT) 

Returns the sign of an expression: 1 if positive, 0 if 0, -1 if negative. 

Returns a value obtained by shifting an INTEGER representation of an argument a 
specific number of bit positions, without wraparound. 

Returns the square root of an expression. 

Returns the sum of all the elements in an array. (Requires MAT) 

Returns the tangent of the angle represented by an expression. 

Returns the number of seconds between midnight and the time represented by the string 
argument. (Requires CLOCK) 


Dealing with Angles and Such 

Six functions are provided for dealing with angles and angular measure (SIN, ASN, COS, ACS, 
TAN, ATN). The default mode for all angular measure is radians. Degrees can be selected with 
the DEG statement. Radians may be re-selected by the RAD statement. It is a good idea to 

explicitly set a mode for any angular calculations, even if you are using the default (radian) 

mode. This is especially important in writing subprograms, as the subprogram inherits the 
angular mode from the context that calls it. When the calling context is restored, the angle 
mode is also restored. 

Range Limits 

It is sometimes necessary to limit the range of excursion of a variable (as in the discussion of 
REAL to INTEGER conversions mentioned in the introduction to this chapter). While it is 
possible to do this with IF...THEN statements: 

200 IF X>Maxx THEN X = Maxx 

210 IF X<Minx THEN X = Minx 

it is more convenient to use the MAX and MIN functions. 

200 X = MIN (MAX ( X »Minx) >Maxx) 

Note that MAX is used to establish the lower bound, and MIN is used to establish the upper 
bound. If you think about it a minute, it makes sense. 
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Rounding 

Rounding occurs frequently in computer operations. The most common rounding occurs in 
printouts and displays, where it can be handled effectively with a USING clause in the output 
operation. For details see the section on Formatted Output in the Using a Printer chapter. This 
works in statements such as PRINT, LABEL, OUTPUT and DISP. 

Sometimes it is necessary to round a number in a calculation, to eliminate unwanted resolution. 
There are two basic types of rounding; rounding to a total number of decimal digits and 
rounding to a number of decimal places (limiting fractional information) . Both types of round¬ 
ing have their own application in programming. 

There is a tendency for the number of decimal places to grow as calculations are performed on 
the results of other calculations. One of the first things covered in training for engineering and 
the sciences is how to handle the growth of the number of decimal places in a calculation. If the 
initial measurements from an experiment produced three digits of information per reading, it is 
very misleading to produce a seven-digit number as the result of a long series of calculations. 
The DROUND function allows you to eliminate the unwanted digits, to produce more realistic 
calculations and answers. 

X=DROUND(SQR(Y A 3+Gr'3) *3) 

It is also possible to round to a number of decimal places. The idea is to eliminate decimal 
representation beyond a specific power of ten. The PROUND function allows you to perform a 
round to any specified power of ten. 

200 X = P R 0 U N D ( X1> P1 a c e s ) 

Random Numbers 

The RND function returns a psuedo-random random number between 0 and 1. Since many 
modeling systems require random numbers with arbitrary ranges, it is necessary to scale the 
numbers. 

200 R=INT(RND*Ran*e>+0ffset 

The above statement will return an integer between Offset and Offset + Ranse. 

The random number generator is seeded with the value 37 480 660 at power-on, SCRATCH, 
SCRATCH A, and prerun. The pattern period is 2 31 -2. You can change the seed with the 
RANDOMIZE statement, which will give a new pattern of numbers. 

Binary Operations 

In actuality, all operations the computer performs are binary. There are, however, some logical 
and bit-level operations available on the computer that are commonly called binary operations. 
When any of these operations are used, the arguments are first converted to INTEGER (if they 
are not already in the correct form) and then the specified operation is performed. It is best to 
restrict bit-oriented binary operations to declared INTEGERS. If it is necessary to operate on a 
REAL, make sure the precautions described under Conversions, at the beginning of this chap¬ 
ter, are employed, to avoid INTEGER overflow. 




Numeric Computation 85 


Array Operations 

An array is a multi-dimensioned structure of variables that are given a common name. The array 
can have one through six dimensions. Each location in an array can contain one variable value, and 
each value has the characteristics of a single variable, depending on whether the array consists of 
REAL or INTEGER values (string arrays are discussed in Chapter 5, “String Manipulation”). Note 
that many of the statements that deal with arrays (such as MAT) require the MAT BIN. 

A one-dimensional array consists of n elements, each identified by a single subscript. A two- 
dimensional array consists of m times n elements where m and n are the maximum number of 
elements in the two respective dimensions. Arrays require a subscript in each dimension, in 
order to locate a given element of the array. Up to six dimensions can be specified for any array 
in a program. REAL arrays require eight bytes of memory for each element, plus overhead; so 
you can see that large arrays can demand massive memory resources. 

An undeclared array is given as many dimensions as it has subscripts in its lowest-numbered 
occurrence. Each dimension of an undeclared array has an upper bound of ten. Space for these 
elements is reserved whether you use them or not. 

Dimensioning an Array 

Before you use an array, you should tell the system how much memory to reserve for it. This is 
called “dimensioning” an array. You can dimension arrays with the DIM, COM, ALLOCATE, 
INTEGER, or REAL statements. An array is a type of variable and as such follows all rules for 
variable names. Unless you explicitly specify INTEGER type in the dimensioning statement, 
arrays default to REAL type. The same array can only be dimensioned once in a context 1 . 
However, as we explain later in this section, arrays can be REDIMensioned. 

When you dimension an array, the system reserves space in internal memory for it. The system 
also sets up a table which it uses to locate each element in the array. The location of each 
element is designated by a unique combination of subscripts, one subscript for each dimension. 
For a four-dimensional array, for instance, each element is identified by four subscript values. 
Each unique set of subscript values points to one, and only one, array element. 

The actual size of an array is governed by the number of dimensions and the subscript range of 
each dimension. If A is a three-dimensional array with a subscript range of 1 thru 4 for each 
dimension, then its size is 4 x 4 x 4, 64 elements. 

When you dimension an array, therefore, you must give not only the number of dimensions but 
also the subscript range of each dimension. Subscript ranges can be specified by giving the 
lower and upper bounds, or by giving just the upper bound. If you give only the upper bound, 
the lower bound defaults to the current option base setting. 


1 There is one exception to this rule: If you ALLOCATE an array, and then DEALLOCATE it, you can dimension the array again. 
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Each context initializes to an option base of 0 (but arrays appearing in COM statements with an (*) 
will keep the base with which they were originally dimensioned). However, you can set the option 
base to 1 with the OPTION BASE command. You can have only one OPTION BASE statement in 
a context, and it must precede all explicit variable declarations. 

The following examples illustrate some of the flexibility you have in dimensioning arrays. 

10 OPTION BASE 1 
20 DIM A(3 »4 >0:2) 



Size 

Lower Bound 

Upper Bound 

1st Dimension 

3 

i 

3 

2nd Dimension 

4 

i 

4 

3rd Dimension 

3 

0 

2 


In this example we portray the first dimension as planes, the second dimension as rows, and the 
third dimension as columns. In general, the last two dimensions of any array always refer to 
rows and columns, respectively. When we discuss two-dimensional arrays, the first dimension 
will always represent rows, and the second dimension will always represent columns. Note also 
in the above example that the first two dimensions use the default setting of 1 for the lower 
bound, while the third dimension explicitly defines 0 as the lower bound. The numbers in 
parentheses are the subscript values for the particular elements. These are the numbers you use 
to identify each array element. 
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10 OPTION BASE 1 
20 COM B(1:5 *2 s G) 


(1,2) 

(1.3) 

(1,4) 

(1,5) 

(1,6) 

(2,2) 

(2,3) 

(2,4) 

(2,5) 

(2,6) 

(3,2) 

(3,3) 

(3,4) 

(3,5) 

(3,6) 

(4,2) 

(4,3) 

(4,4) 

(4,5) 

(4,6) 

(5,2) 

(5,3) 

(5,4) 

(5,5) 

(5,6) 


Size 

Lower Bound 

Upper Bound 

1st Dimension 

5 

i 

5 

2nd Dimension 

5 

2 

6 


10 OPTION BASE 1 

20 ALLOCATE INTEGER C(2:4»-2:2) 


(2,-2) 

(2,-1) 

(3,0) 

(2,1) 

(2,2) 

(3,-2) 

(3,-1) 

(3,0) 

(3,1) 

(3,2) 

(4,-2) 

(4,-1) 

(4,0) 

(4,1) 

(4,2) 


Size 

Lower Bound 

Upper Bound 

1st Dimension 

3 

2 

4 

2nd Dimension 

5 

-2 

2 
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10 OPTION BASE 0 

20 REAL D(1>0) 


( 0 , 0 ) 


( 1 . 0 ) 


Size 

Lower Bound 

Upper Bound 

1st Dimension 

2 

0 

i 

2nd Dimension 

1 

0 

0 


10 COM E(-3:0) 


(-3) 


(- 2 ) 


(- 1 ) 


( 0 ) 


Size 

Lower Bound 

Upper Bound 

1st Dimension 

4 

-3 

0 
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10 OPTION BASE 0 
20 INTEGER F(1»4»-l:2) 



Size 

Lower Bound 

Upper Bound 

1st Dimension 

2 

0 

1 

2nd Dimension 

5 

0 

4 

3rd Dimension 

4 

-1 

2 



Arrays are limited to six dimensions, and the subscript range for each dimension must lie 
between —32767 and 32767. (REDIM and ALLOCATE allow the subscript range to go down 
to -32768, but the total size of each dimension must be less than 32768 elements.) For the 
most part, we use only two-dimensional examples since they are easier to illustrate. However, 
the same principles apply to arrays of more than two dimensions as well. 


Note 

Throughout this chapter we will be using DIM statements without 
specifying what the current option base setting is. Unless explicitly 
specified otherwise, all examples in this chapter use option base 1. 
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As an example of a four-dimensional array, consider a five-story library. On each floor there are 
20 stacks, each stack contains 10 shelves, and each shelf holds 100 books. To specify the 
location of a particular book you would give the number of the floor, the stack, the shelf, and 
the particular book on that shelf. We could dimension an array for the library with the state¬ 
ment: 

DIM Lib r a ry(5 >20 >10 >100 ) 

This means that there are 100,000 book locations. To identify a particular book you would 
specify its subscripts. For instance, Lit>rary(2>12>3>35) would identify the 35th book on 
the 3rd shelf of the 12th stack on the 2nd floor. 

We can imagine accessing a particular page of a book by using a 5-dimensional array. For 
instance, if we dimension an array, 

DIM Pa 3 e(5 >20 >10 >100>200) 

then Pa $e ( 1 >7 >2 >19 >130) would designate page 130 of the 19th book on the 2nd shelf 
of the 7th stack on the 1st floor. 

We could specify words on pages by using a 6-dimensional array. Six dimensions is the 
maximum, though, so we could not specify letters of words. 

Also, you can dimension more than one array in a single statement by separating the declara¬ 
tions with a comma. For instance, 

10 DIM At 1 >3>4) >B(-2:0>2:5) >C(5) 
would dimension all three arrays: A, B, and C. 

Problems with Implicit Dimensioning 

In any environment, an array must have a dimensioned size. This size can be passed into an 
environment through a passed parameter list or a COM statement. It may be explicitly dimen¬ 
sioned through COM, INTEGER, REAL or ALLOCATE. It can also be implicitly dimensioned 
through a subscripted reference to it in a program statement other than a MAT or a REDIM 
statement. An attempt to use an array that does not have a dimensioned size in the current 
environment in a MAT or REDIM statement will result in an error. In other words, MAT and 
REDIM statements cannot be used to implicitly dimension an array. 
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Finding Out the Dimensions of an Array 

There are a number of statements that allow you to determine the size and shape of an array. To 
find out how many dimensions are in an array, use the RANK function. For instance: 

OPTION BASE 0 
DIM F(1 »4 * - 1 : 2 ) 

PRINT RANK (F) 

would print 3. 

The SIZE function returns the size (number of elements) of a particular dimension. For instance, 
SIZE (F #2) 


would return 5, the number of elements in F’s second dimension. 

To find out what the lower bound of a dimension is, use the BASE statement. Referring again to 
array F 

BASE (F > 1 ) 

would return a 0, while, 

BASE (F >3) 

would return a -1. 

By using the SIZE and BASE statements together, you can determine the upper bounds of any 
dimension (e.g., SIZE + BASE - 1 = Upper Bound). 

It may seem pointless to have all these functions that return the dimension specifications which 
you yourself assigned. After all, if you assigned the dimensions, you should know what they 
are; and if you forget, you can always look at the appropriate dimensioning statement. Howev¬ 
er, these functions are powerful tools for writing programs that perform functions on an array 
regardless of the array’s size or shape. In addition, the system automatically redimensions 
arrays during certain operations. The functions discussed above provide you with a means for 
determining the new dimensions. As an example of a general purpose program utilizing these 
statements, consider the subprogram below which prints a two-dimensional array in rows and 
columns. 

100 SUB Printmat(Array(*)) 

110 OPTION BASE 1 

120 FOR Row=BASE(Array*1) TO SIZE<Array>1)+BASE<Array»1)-1 
130 FOR Column=BASE(Array»2) TO SIZE(Array>2)+BASE(Array ,2)- 1 
140 PRINT USING "DDDD . DD ,XX »#" 5 A r ray ( Row »Co 1 umn ) 

150 NEXT Column 

ISO PRINT 

170 NEXT Row 
180 SUBEND 
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Filling an Array 

Once an array has been dimensioned, the next step is to fill it with useful values. Initially, every 
element in an array equals zero. There are a number of different ways to change these values. 
The most obvious is to assign a particular value to each element. This is done by specifying the 
element’s subscripts. For instance, the statement, 

A < 3 »4 ) = 1 3 

would assign the value 13 to the element in the third row and fourth column of A. You must 
give enough subscripts for the system to identify a single element. For a three-dimensional 
array, for instance, you would provide three subscripts. All subscripts, moreover, must lie within 
the dimensioned range. If you use out-of-range subscripts, the system returns an error. 

For some applications, you may want to initialize every element in an array to some particular 
value. You can do this by assigning a value to the array name. However, you must precede the 
assignment with the MAT keyword. For example, 

MAT A = (10) 

will assign the value 10 to every element in array A regardless of A’s size. Note that the numeric 
expression on the right-hand side of the assignment must be enclosed in parentheses. 

Another way to assign values to an array is by using the READ and DATA statements. The DATA 
statement allows you to create a stream of data items, and the READ statement enables you to 
enter the data stream into an array. For example: 

10 OPTION BASE 1 
20 DIM A(3 ,3) 

30 DATA -4 *36 *2.3 >5 >89 >17 * - 6 >-12 >42 
40 READ A(*) 

50 END 

The asterisk in line 40 is used to designate the entire array rather than a single element. Note also 
that the right-most subscript varies fastest. In this case, it means that the system fill an entire row 
before going to the next one. The READ/DATA statements are discussed further in Chapter 7. 

If we use the Printmat subprogram (shown on previous page) to display A, we get: 

-4.00 3G.00 2.30 

5.00 89.00 17.00 

-6.00 -12.00 42.00 

Copying Arrays 

A fourth way to fill an array is to copy the elements from one array into another. Suppose, for 
example, that you have the two arrays A and B shown below. 

A B 


0 0 0 


3 5 

0 0 0 


8 2 

0 0 0 


1 7 
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Note that A is a 3x3 array which is filled entirely with 0’s, while B is a 3x2 array filled with 
non-zero values. To copy B to A, we would execute: 

MAT A = B 


Again, you must precede the assignment with MAT. The system will automatically redimension 
the ‘‘result array” (the one on the left-hand side of the assignment) so that it is the same size as 
the “operand array” (the one on the right side of the equation.) There are two restrictions on 
redimensioning an array. 

• The two arrays must have the same rank (e.g., the same number of dimensions.) 

• The dimensioned size of the result array must be at least as large as the current size of the 
operand array. 

If the system cannot redimension the result array to the proper size, it returns an error. 

Automatic redimensioning of an array will not affect the lower bounds, only the upper bounds. 
So the BASE values of each dimension of the result array will remain the same. Also keep in 
mind that the size restriction applies to the dimensioned size of the result array and the current 
size of the operand array. Suppose we dimension arrays A, B and C to the following sizes: 

10 OPTION BASE 1 

20 DIM A ( 3 >3 ) »B ( 2 >2 ) >0 ( 2 >4 ) 


We can execute, 
MAT A=B 


since A is dimensioned to 9 elements and B is only 4 elements. The copy automatically 
redimensions A to a 2x2 array. Nevertheless, we can still execute: 

MAT A=C 

This is because the nine elements originally reserved for A remain available until the program is 
scratched. A now becomes a 2x4 matrix. After MAT A = C, we could not execute: 

MAT B=A 
or 

MAT B=C 

since in each of these cases, we are trying to copy a larger array into a smaller one. But we could 
execute 

MAT C=A 

after the original MAT A = B assignment, since C’s dimensioned size (8) is larger than A’s current 
size (4). 
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Extracting Values From Arrays 

As with entering values into arrays, there are a number of ways to extract values as well. To 
extract the value of a particular element, simply specify the element’s subscripts. For instance, 
the statement, 

X = A < 3 ,a >2) 

would assign the value of the element occupying the given location in A to the variable X. The 
system will automatically convert variable types. For example, if you assign an element from a 
Real array to an Integer variable, the system will perform the necessary rounding. 

Certain operations (e.g., PRINT, OUTPUT, ENTER and READ) allow you to access all ele¬ 
ments of an array merely by using an asterisk in place of the subscript list. The statement, 

PRINT A(*)5 

would display every element of A on the current PRINTER IS device. The elements are display¬ 
ed in order, with the rightmost subscripts varying fastest. The semi-colon at the end of the 
statement is equivalent to putting a semi-colon between each element. When they are display¬ 
ed, therefore, they will be separated by a space. (The default is to place elements in successive 
columns.) 

The asterisk is also used to pass an array as a parameter to a function or subprogram. For 
instance, to pass an array A to the Printmat subprogram listed earlier, we would write: 

P r i n t m a t ( A ( * ) ) 

In addition to extracting the values of elements in an array, there are also functions that compute 
the sum of an entire row or column of an array. However, since these functions are limited to 
two-dimensional arrays, we will reserve their discussion for the section on matrices. The statement 
that returns the sum of all elements in an array, however, works for arrays of any dimension. Given 
the array A below, 

A 

" 4 2-1 

3 8 16 

_ —5 2 0 . 

the function, 

SUM(A) 


would return 29. 
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Redimensioning Arrays 

In our discussion of copying arrays we saw that the system automatically redimensions an array if 
necessary. You can also explicitly redimension an array with the REDIM statement. As with auto¬ 
matic redimensioning, the following two rules apply to all REDIM statements: 

• A REDIMed array must maintain the same number of dimensions. 

• You cannot REDIM an array so that it contains more elements than it was originally 
dimensioned to hold. 

Suppose A is the 3x3 array shown below. 

A 

"l 2 3~ 

4 5 6 
1 8 9_ 

To redimension it to a 2x4 array, you would execute: 

REDIM A(2 >4) 

The new array now looks like the figure below: 

A 

fl 2 3 4l 
[5 6 7 8j 

Note that it retains the values of the elements, though not necessarily in the same locations. For 
instance, A (2,1) in the original array was 4, whereas in the redimensioned array it equals 5. If 
we REDIMed A again, this time to a 2x2 array, we would get: 

REDIM A(0: 1 *0: 1 ) 


[3 i] 


We could then initialize all elements to 0: 


[2 S] 


MAT A = (0) 
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It is also important to realize that elements that are out of range in the REDIMed array still retain 
their values. The fifth thru ninth elements in A still equal 5 thru 9 even though they are now 
inaccessible. If we REDIM A back to a 3x3 array, these values will reappear. For example: 

REDIM A ( 3 * 3 ) 
produces: 

A 

"o 0 o" 

0 5 6 
1 8 9_ 

One of the major strengths of the REDIM statement is that it allows you to use variables for the 
subscript ranges: this is not allowed when you originally dimension an array. In effect, this 
enables you to dynamically dimension arrays. This should not be confused with the ALLO¬ 
CATE statement which allows you to dynamically reserve memory for arrays. In the example 
below, for instance, we enter the dimensions from the keyboard. 

10 OPTION BASE 1 

20 DIM A(100*100) ! 1000 ELEMENT ARRAY 

30 INPUT "Enter lower arid upper bounds of dimensions"* 

Low 1 >Up 1 *Low2 >Up2 

40 IF (Up 1-Low 1 +1 )*(Up2-Lo w2+1)>10000 THEN Too.biS 
50 REDIM A(Low1:Up1*Low2:Up2) 

Line 40 tests to see whether the new dimensions are too big. If so, program control is passed to 
a line labelled “Too_big”. If line 40 were not present, the REDIM statement would return an 
error if the dimensions were too large. 

Arrays and Arithmetic Operators 

It is possible to multiply, divide, add, and subtract scalars to an array, as well as to add, subtract, 
multiply, and divide one array to another. All arithmetic functions involving arrays must be 
preceded by the MAT keyword. The specified operation is performed on each individual 
element in the operand array(s) and the results are placed in the result array. The result array 
must be dimensioned to be at least as large as the current size of the operand array(s). If it is of a 
different shape than the operand array(s), the system will redimension it. Given the array A 
below, note how these arithmetic functions are performed. 

A 

"l 2 3" 

4 5 6 
7 8 9 


B 

4 5 6 

7 8 9 

10 11 12 


MAT B = A+(3) 
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MAT C= B/(2) 


C 

2 2.5 3 

3.5 4 4.5 

.5 5.5 6 

MAT C= C*<1 + 1 + 1) 


C 

6 7.5 9 

10.5 12 13.5 

.15 16.5 18 

Note that the result array can be the same as the operand array. Also, the scalar must be 
enclosed in parentheses. 

In addition to performing arithmetic operations with scalars, you can also add, subtract, divide 
and multiply two arrays together. Except for multiplication with an asterisk, which is described 
later, these functions proceed as follows: Corresponding elements of each operand array are 
processed according to the specified operation, and the result is placed in the result array. The 
two operand arrays must be exactly the same size though their particular subscript ranges can 
be different. For multiplication, use a period rather than an asterisk. Using arrays A and B 
above, the statement, 

MAT D= A+B 
would give the array: 

D 

" 5 7 9' 

11 13 15 

.17 19 21_ 

The statement, 

MAT B= A.B 

would give: 



B 


4 

10 

18 

28 

40 

54 

70 

88 

108 


Again, the dimensioned size of the result array must be as large as the current size of each 
operand array. The two operand arrays must be identical in shape and size, but not necessarily 
in subscript ranges. For instance, A and B could have been dimensioned: 


10 


DIM A(1:3 >2:4) *B(-1 :1 .0:2) 
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Boolean Arrays 

In addition to the arithmetic operators, you can also use relational operators with arrays. The 
result is a boolean 1 array (e.g., an array composed entirely of l’s and 0’s). Given array B above, 
suppose you wanted to know how many elements were greater than 50. First you execute the 
statement, 

MAT F = B >(50) 
which results in the array: 


F 

"o 0 o" 

0 0 1 
_1 1 1 _ 

Then you execute the statement, 

PRINT SUM(F) 

which causes the computer to display “4” on the current PRINTER IS device. 

You can also compare two arrays to each other. If, for example, you wanted to compare the 
two arrays below, 

A 

1 3 5 

2 8 7 
_1 4 6,. 

you could execute the statement: 

MAT C= A=B 

By looking at C, you can tell which elements are the same for both A and B. 

C 

'l 1 0 
1 0 1 
1 1 0 


1 3 4 

2 0 7 
1 4 4 


1 Strictly speaking, these are not really boolean arrays since the values of the elements are not TRUE and FALSE. 
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Reordering Arrays 

The MAT REORDER statement allows you to re-arrange an array so that one dimension is in a 
particular order. The new order is specified in a vector (a vector is a one-dimensional array). 
The vector contains the subscripts of the reordered dimension in their new order. The sub¬ 
scripts must correspond to the array’s current dimensions and subscript ranges. Suppose A is 
the array below. Let us also assume that A has been dimensioned in OPTION BASE 1, and that 
the upper bound to both dimensions is 3. 

A 

1 3 2" 

4 5 7 
_6 8 9_ 

To reverse the order of the rows, we would first dimension a vector, 

10 DIM Reuerse(3) 

and then assign its elements the following values: 

Reue rse(1)=3 
Reue rse(2)=2 
Reuerse(3)=l 

The array Reue rse now appears: 

Reverse 
[3 2 1] 

If we execute the statement, 

MAT REORDER A BY Reuerse 

the result array will be: 

A 

'6 8 9" 

4 5 7 
1 3 2_ 

Note that the rows are exchanged, rather than the columns. This is because the default is to 
re-order the 1st dimension. However, you can override the default by specifying a particular 
dimension to be re-ordered. For example, if we wanted to reverse columns rather than rows, 
we could use the same vector, but this time specify dimension 2: 

MAT REORDER A BY Reversed 


A 


A 

6 8 9" 


"9 8 6“ 

4 5 7 

=> 

7 5 4 

1 3 2 


2 3 1 


The transformation would be: 
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Remember that although our examples are confined to two dimensions for illustrative pur¬ 
poses, the same principles apply to arrays of three and more dimensions. In a three- 
dimensional array, for instance, reordering the 1st dimension would reorder planes rather than 
rows or columns. 

In most cases, rather than creating a reorder vector and assigning values to it, you will already 
have a vector as the result of a sort operation. This is described in the next section. 

Sorting Arrays 

A frequent operation performed on arrays is a sort. Sorting an array rearranges the array so that 
one dimension (which you specify) is in numerical order. Given the array A below, watch how 
the MAT SORT changes it. 

A 

‘5 6 8“ 

3 5 1 
_2 4 8_ 

MAT SORT A ( * > 1 ) 

A 

"2 4 8 
3 5 1 
_5 6 8_ 

The asterisk specifies the dimension to be sorted, and the subscript(s) tells which elements in 
that dimension to use as the sorting values. In the example above, we told the system to sort 
rows (asterisk is located in the first subscript position), and to use the first element in each row 
as the sorting value. With the new array A (from the sort performed above), the following 
statement will sort columns using the second element in each column as the sorting value. 

MAT SORT A (2 >* ) 


A 

"8 2 4“ 

1 3 5 
_8 5 6_ 

The key values in this sort are 1, 3 and 5, the second elements in each column. Sorting by 
placing the lowest values first is known as sorting by “ascending” order. This is the default. You 
can also sort by “descending” order by specifying the secondary keyword DES. For instance, 
the statement, 

MAT SORT A(* >2) DES 


would produce the following transformation: 


A A 


'8 2 4" 


8 

5 

6 

1 3 5 


1 

3 

5 

8 5 6 


8 

2 

4 
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Sometimes the values of two or more sorting elements are the same. For instance, if we sorted 
A by rows using the first element, 

MAT SORT A(* »1) 

we get: 


A 


A 

8 5 6" 


"l 3 5" 

1 3 5 


8 5 6 

8 2 4 


8 2 4 


The first elements in the last two rows are the same, so the system leaves them in the order they 
held before the sort. However, you can specify a second sort element to be used in the case of 
ties. We could execute: 

MAT SORT A(* >1) »<* ,2) 

This tells the system to sort by rows using the first element as the sorting value; and in the case 
of ties, to use the second element. The result array would be: 


A A 


1 3 5 


1 

3 

5 

8 5 6 


8 

2 

4 

8 2 4 


8 

5 

6 


The maximum number of sorting keys is 25. 

If a key is specified that is recognized by the system as rendering all other keys redundant (such as a 
non-substringed key for a one dimensional string array) no other keys can be specified. However, if 
the computer cannot tell that keys are redundant (such as MAT SORT A(*>X)»A(*>Y) with X 
equal to Y) it will permit redundant keys. Redundant keys will slow down execution of the MAT 
SORT statement. If you include the DES secondary word, it refers only to the sort element which 
immediately precedes it. 

Sorting to a Vector 

So far, all of our sort examples have actually re-arranged the array in question. Alternatively, 
you can record the new order in a vector and leave the array intact. The vector must have been 
dimensioned to have at least as many elements as the current size of the array being sorted. If 
necessary, the system will redimension the vector. Thus, executing the statement: 

MAT SORT A(3 *#) TO Meet 
with the array A: 


A 

1 3 5" 

8 2 4 
.8 5 6_ 

The array A remains unchanged, but the vector Meet now contains the values: 

Vect 

[2 3 l] 
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This assumes that the array A has been dimensioned so that the subscript range is 1 thru 3. If A 
had been dimensioned. 

10 DIM A ( 1 : 3 > - 1 : 1 ) 
then Meet would contain the values: 

Vect 

[0 1 - 1 ] 

This vector should look very reminiscent of the vectors used to reorder arrays. And, in fact, you 
can use these vectors in a MAT REORDER statement to rearrange the array. That is, we could 
now execute: 

MAT REORDER A BY Meet#2 
and the new array would be: 

A 

"3 5 l" 

2 4 8 
_5 6 8_ 

Note that the dimension number in the MAT REORDER statement corresponds to the position 
of the asterisk in the MAT SORT statement. 

Sorting to a vector is particularly useful if you want to sort the same array along different 
dimensions or using different sort elements. Each sort can be stored in a vector to be used later. 
Meanwhile, the original array remains unchanged. 

In addition, sorting to a vector allows you to use the same sorting order with parallel arrays. 
That is, if you have several arrays that contain data about the same elements, you can sort one 
of them, and then use that same sorting order to reorder the others. 

Finally, sorting to a vector enables you to manipulate an unsorted array as if it were sorted. For 
instance, suppose you have the array shown below: 

A 

"2 7 4" 

0 1 8 
_5 3 1_ 

Let us also assume that the subscript range for each dimension in A is 1 thru 3. If we sort A to a 
vector B, 

MAT SORT A(* * 1) TO B 

we can then use B to define elements in A. For instance, to get the value of A( 1,1) in its sorted 
form, we could write: 


X = A(B(1) »1 ) 
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In this case, X would equal 0. By incrementing the subscript value of B, we can simulate a 
sorted A. 

We should point out again that although these examples are two-dimensional, the same princi¬ 
ples apply to arrays of any rank. You must have one, and only one, asterisk in the subscript list 
of a sort. The other subscripts specify the particular elements to be used as the sorting keys. 

Matrices and Vectors 

A two-dimensional numeric array is called a “matrix” and a one-dimensional numeric array is 
called a “vector”. An entire branch of mathematics is devoted to matrices and vectors, and their 
applications are surprisingly broad. There are certain operations that are frequently performed on 
matrices which have been incorporated in BASIC. Keep in mind that the functions described in this 
section apply only to two-dimensional, and occasionally one-dimensional arrays, but never to 
arrays of more than two dimensions. 

Matrix Multiplication 

You may recall from our discussion of arrays and arithmetic operations that the asterisk (*) is 
reserved for matrix multiplication. If A is an i-by-k matrix and B is a k-by-j matrix, then c = A*B is 
defined by the following equation: 


n 



k= 1 


Translated into english, this equation means that the element in the ith row and jth column of 
the product (C) is the sum of the products by pairs of the elements in the ith row of A and the jth 
column of B. A couple of examples will help make this clear. 

Suppose A and B are the matrices shown below. 


A 

3 8 2 
1 6 5 

4 2 0 


B 

1 -2 3 
-6 4 7 

0 8 2 


If C = A*B, then : 

C(1ti)=A(1tl)*B(ltl)+A(lt2)*B<2tl)+A(1t3)*B(3t1)=(3*1)+(8*-6)+(2*0)=-45 
0(2 tl)=A<2tl)*B(1 it)+A(2 t2)*B(2 tl)+A(2 t3)*B(3.1) = (1*1>+(6*-6)+<5*0)=-35 
C(3t2)=A(3tl)*B(lt2)+A(3t2)*B(2t2)+A(3t3)*B(3t2)=(4*-l)+(2*4)+(0*8)=0 

Following this procedure for each element in C, we get the matrix shown below. 


C 

-45 42 69 
-35 62 55 
- 8 0 26 


MAT C=A*B 
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Note that the product is a 3x3 matrix. There are three general rules to matrix multiplication: 

• Multiplication between two matrices is legal only if the second dimension of the first array 
is the same size as the first dimension of the second array. That is, the two inner dimen¬ 
sions must be the same. 

• The result matrix will have the same number of rows as the first operand matrix and the 
same number of columns as the second operand matrix. That is, the dimensions of the 
result matrix will be the same as the outer dimensions of the operand matrices. 

• The result array cannot be the same as either of the operand arrays. For example, 

MAT A= A*B 
is an illegal statement. 

If A is a 2x3 matrix and B is a 3x2 matrix, A*B will result in a 2x2 matrix. B*A, on the other hand, 
produces a 3x3 matrix. Given the two matrices below, you can see how their position in the 
equation affects the product. 


A 


B 

[6 8 -l] 


-l 

1 

|_2 -3 4j 

A*B 


2 -2 

3 4_ 

B*A 

I" 7 -14] 

4 

-11 

5 

|_4 24 J 

8 

22-10 


26 

12 

13_ 


Multiplication With Vectors 

We described a vector as a one-dimensional array. For instance, 

10 DIM A(3) 

would create a vector with three elements and a rank of 1. Suppose we give A the values shown 
below. 


A 

[1 2 3] 

Notice that we have portrayed A as a row vector. We could have just as easily portrayed A as a 
column vector: 


A 

l' 

2 

3 
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So which is it? A row vector or a column vector? Actually, a vector can behave like either 
depending on its position in an equation. If a vector is the first operand in a multiplication, then 
it acts like an lXn array (row vector); if it’s the second operand, it behaves like a nXl array 
(column vector); and if it’s the result array, it can act like either. A few examples will help 
illustrate these principles. Let A be the vector shown above, and B, C, and D be the arrays 
shown below. 


B C D 


"l 2 3" 


"0 0 0 " 

4 5 6 


0 0 0 

7 8 9 


0 0 0 


Let us suppose that D has been explicitly defined as a two-dimensional array: 
10 DIM D(3 > 1 ) 


If we execute: 

MAT C= A*D 


we get: 


C 

[ 12 ] 


Since A is the first operand, it behaves like a 1x3 matrix. The equation, therefore, is: 


C=[l 2 3]* 


2 

2 

2 


The result is a lxl matrix. If we try to reverse the order: 
MAT C=D*A 


the system returns: 

ERROR IB Improper dimensions 
This is because we tried to multiply a 3x1 matrix by a 3x1 matrix: 



"2" 


T 

C = 

2 

* 

2 


2 


3 


Since the inner dimensions are not the same, the system returns an error. Suppose we try: 


MAT C = B*A 
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In this case, we are multiplying a 3x3 array to a column vector. 



"l 2 3" 


V 

c= 

4 5 6 

* 

2 


7 8 9 


3 


The result is a 3x1 matrix: 

C 

'14" 

32 

.50. 


If the result array is a vector, then it will behave like either a row vector or a column vector 
depending on which is called for. The only other possibility is if both operand arrays are vectors. 
In this case, the result is always a lxl array. For instance, if A and B are the vectors below, 



A 


B 


"2" 


o' 


4 


1 


6 


-1 

then multiplying A by B results in the equation: 

MAT C = A*B 







o' 


C = 

* 

1-1 

v£> 

CM 

1_1 

1 


1 

C equals -2. Reversing the operand arrays, we get: 
MAT C = B* A 


c=[o 1 -l] * 


2 

4 

6 


Again, C equals - 2. Because the product of two vectors is always a single element, BASIC has 
a DOT function that multiplies two vectors and comes up with a Real or Integer numeric. For 
example, 


X=D0T(A > B) 


would assign the value — 2 to X. If both vectors are Integer, then the product is an Integer. 
Otherwise, the product is Real. The two vectors must be the same size or the system will return 
an error. 
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Identity Matrix 

An “identity matrix” is defined as a matrix which, when multiplied to another matrix A, pro¬ 
duces the same matrix A. It is analogous to a 1 in normal arithmetic. For example, if I stands for 
an identity matrix, then A = I * A and also A = A * I. In order for an identity matrix to exist at all, A 
must be a square matrix (e.g., it must have the same number of columns as rows). 

As it turns out, all identity matrices have the same form. They are square and consist of l’s 
along the main diagonal, and 0’s everywhere else. For example, if A is a 3x3 matrix, then the 
identity matrix for A is: 


I 

"l 0 o" 

0 1 0 
.0 0 1 _ 

For a 4x4 matrix, I would be: 

I 

1 0 0 o" 

0 10 0 
0 0 10 
. 0001 . 

Since identity matrices are used frequently in matrix arithmetic, BASIC has a special function 
(IDN) that turns a square matrix into an identity matrix. For instance: 


10 

OPTION BASE 1 

20 

DIM 

1(2f2) 

30 

MAT 

I = I DN 


« 



♦ 



The matrix I now contains the elements: 

If I was not a square matrix, line 20 would have returned an error. 

Inverse Matrix 

Although division is not defined for matrices, there is a similar operation which involves finding 
the inverse of a matrix. As with identity matrices, a matrix must be square in order to have an 
inverse. Inverse matrices are notated by a superscript -1. If A is a square matrix, then A 1 
denotes its inverse. The inverse is defined by the equation: 

A* A -1 = I 

where I is the identity matrix. You can see how similar this is to division since, if A were a real 
number, then: 

A*(l/A) = 1 
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The inverse of a matrix is found by using the INV function. For instance, the inverse of: 

A 

' 02 O' 

-12 0 
. 2 0 2 . 

is found by executing: 

MAT A_in y = I NO(A) 

The system computes the values of the inverse and places them in the matrix A_ i n v: 

A_inv 

1 -1 o" 

.5 0 0 

_-l 1 ,5_ 

To check that this is really the inverse, you could execute the statement: 

MAT B= A*A_inu 

As expected, B turns out to be an identity matrix: 

B 

"l 0 0" 

0 1 0 
_0 0 1_ 

Unfortunately, these expectations are not always fulfilled. Some matrices do not have an 
inverse. In other words, for a certain matrix called A, there exists no other matrix that, when 
multiplied to A produces an identity matrix. Matrices that don’t have an inverse are called 
“singular”. Singular matrices are easily detected and therefore aren’t too dangerous. A more 
troublesome type of matrix is one that is “ill-conditioned”. Ill-conditioned matrices are ones 
whose inverse can’t be found by the computer because of round-off errors. These are difficult 
to detect and almost impossible to correct. We’ll talk more about singular and ill-conditioned 
matrices, but before we do, we should discuss why you’d use an inverse in the first place. 

Solving Simultaneous Equations 

One of the most common applications of matrices is in the solution of simultaneous equations. 
Suppose we have the three equations shown below: 

4X + 2Y - Z = 5 
2X-3Y + 3Z = 5 
X + Y-2Z= -3 

Note that there are three unknowns (X,Y, and Z) and three equations. This is a necessity for 
solving by matrix arithmetic: you must have the same number of equations as unknowns. We 
can re-write these equations in matrix format as the product of two arrays: 


"4 2 -l" 


"x" 


5“ 

2-3 3 

* 

Y 

= 

5 

1 1 -2 


Z 


-3 
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For the sake of simplicity, let’s name these three arrays A, B, and C. The equation, therefore, is: 
A*B = C 


If we multiply both sides of the equation by the inverse of A, we get: 


A- I *A*B = A“ 1 *C 


Since A **A is simply a 3x3 identity matrix, the equation simplifies to: 

I *B = A _1 *C 

which further simplifies to: 

B = A- 1 *C 

Remember, B is the matrix that contains the three variables X,Y and Z. To solve for these 
variables, therefore, all we have to do is multiply the matrix C by A -1 . This is accomplished in the 
program lines listed below. 


200 

DIM Solution(3)*A_inu(3*3) 

220 

MAT A. 

„inv=INV<A) 

230 

MAT Solution 2 A-inu*C 

240 

PRINT 

"X=" {Solution(1> 

250 

PRINT 

"Y =" isolation(2) 

2G0 

PRINT 

♦ 

♦ 

" Z = " 5 S o 1 u t i o n ( 3 ) 


When we run this program, it will print the values of X, Y, and Z. The values are: 

X = 1 
Y = 2 
Z = 3 

For any set of simultaneous equations where there are the same number of unknown variables 
as there are equations, there are three possible classes of solution. 

• There is no solution (e.g., there exist no values for the variables such that all of the 
equations are true). 

• There are an infinite number of solutions. 

• There is one, and only one, solution. 

The first two cases are called “singular” sets of equations. You may recall that a singular matrix 
is one that has no inverse. It should not be surprising, therefore, that singular sets of equations 
always result in singular matrices when they are translated to matrix form. This is explained in 
the next section. 
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Singular Matrices 

Any set of equations that has no solution or an infinite number of solutions is singular. Likewise, 
the matrix formed from these equations is also singular. More specifically, we mean the matrix 
on the left-hand side of the equation, what we’ve been calling matrix A. Consider the two 
equations listed below: 

4X + 6Y-5 
4X + 6Y = 6 

Obviously, there is no solution to this set of equations because any values assigned to X and Y 
will make only one of the equations true, not both. It is important to realize, however, that the 
singularity of these equations has nothing to do with the values on the right hand side of the 
equation. If, for example, we made the two equations the same, 

4X + 6Y = 6 
4X + 6Y = 6 

then there would be an infinite number of solutions. For instance, X could equal 0 and Y equal 
1 , or X could equal 1.5 and Y could equal 0. In fact, so long as X= 1.5(1-Y), the two equations 
will always be true. What is important here is that the two equations, 

4X + 6Y = 

4X + 6Y = 

will be singular regardless of what we put on the right-hand side of the equal sign. If we translate 
these equations into matrix form, we get: 

K a - [¥] 

The matrix, 

[i t] 

is singular: it has no inverse. If, however, we call this matrix A and do an INV on it, the system 
will not report an error. On the contrary, it will go ahead and find what it thinks is an inverse. 
However, whatever matrix it comes up with will not be the inverse. Let’s see what happens with 
our singular matrix A. 

MAT A_irm = INU< A) 

PRINT A_inv(*> 

When we execute these statements, the system will display the following: 

.GGG66GGGG6G7 .1BGBGGGGGGG7 0 -1 

Arranging these values in the proper rows and columns, we get: 

A_inv 

I”. 66666666667 0"| 

|_. 16666666667 -lj 
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To see whether this is a real inverse, we can multiply it by A. If it is the inverse, the product 
should be an identity matrix. 

MAT I = A*A_inu 


I 

[3.33333333333 5 "I 

L -4 -6 J 

Obviously, the system has made a mistake — A_ i n v is not the inverse of A. So how do we 
know if an inverse is valid? Or, to put it another way, how do we detect a singular matrix? We 
have just seen one method: multiply the matrix by its inverse and see whether you get an 
identity matrix. There is, however, a much easier method. You simply look at the “determi¬ 
nant” of the matrix. 

The Determinant of a Matrix 

The determinant of a matrix is defined somewhat mysteriously as the sum of all possible 
products formed by taking one element from each row in order starting from the top and one 
element from each column, where the sign of each product depends on the permutation of the 
column indices. 

It’s not really important that you understand how to calculate a determinant since the computer 
does it for you whenever you use the DET function. For instance, to print the determinant of 
matrix A, you would write: 

PRINT DET(A) 

Also the determinant is a byproduct of inversions. Thus, whenever you invert a matrix, the 
system computes the determinant and stores it. If you use DET without specifying a matrix, the 
system will return the determinant of the matrix most recently inverted. For example, 

MAT A_inv=INU<A) 

PRINT DET 

would print the determinant of A. 

Although the computation of the determinant is quite complex, its significance is very simple. If 
the determinant of a matrix equals 0, either a REAL underflow occurred during the inversion or 
the matrix is singular. To find out if an inversion is invalid, therefore, you merely test the 
matrix’s determinant. If the determinant is zero, then the inverse is invalid. For example, if A is a 
square matrix, we could execute: 


100 MAT A_inu = INV(A) 

110 IF DET = 0 THEN Singular 
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If A is singular, program control is passed to a line named “Singular”. Note that we did not have 
to specify a matrix in line 110 since A was the last matrix inverted. 

Unless you know for certain that a matrix is not singular, we recommend that you use the 
determinant test after each inversion. Otherwise, you may perform calculations using an invalid 
inverse. 

Ill-Conditioned Matrices 

In a few unusual cases, the inverse of a matrix will be invalid even though the determinant of 
the matrix is non-zero. These situations occur due to round-off errors internal to the computer. 
They are difficult to detect and even more difficult to correct. Fortunately, they occur very 
rarely. Unless you are having problems with a program involving matrix operations producing 
unexpected results, you can skip over to “Miscellaneous Matrix Functions.” If you are having 
problems, listed below is an example of an ill-conditioned set of equations. 

Xt + 0 X 2 + 3X 3 + 8 X 4 = 12 
2Xi + X 2 + 6 X 3 + 15.9X4 = 24.9 
3X, + X 2 + 8 . 9 X 3 + 24X 4 = 36.9 
4Xt + X 2 + II. 9 X 3 + 32 X 4 = 48.9 

We have selected the numbers on the right-hand side of the equation so that all of the X’s equal 
1. Watch what happens though when we try to solve these equations through matrix inversion. 
First, we set up the equations in matrix format. 

A Var Ans 


”1 

0 

3 

8 


"xi" 


"12 

2 

1 

6 

15.9 

* 

X2 

= 

24.9 

3 

1 

8.9 

24 


X3 


36.9 

4 

1 

11.9 

32 


X4 


48.9 


Then we execute the program statements below. 


100 

MAT 

A_ i ri 

v = 

I NO(A) 

110 

MAT 

0 a r = 

A_ 

i n v * A ri s 

120 

FOR 

Y= 1 

T0 

4 

130 

PRINT 

Us 

in* .K( ,,M >D t"" > = "" >K" 5Y t0ar(Y) 

140 

NEXT Y 




The computer displays: 

X(1)= 256 
X < 2 ) =0 
X(3)=-32 
X ( 4 ) = - 1 G 


Obviously something has gone wrong. The problem is that the inverse found by the computer is 
far off the mark from the actual inverse. The system of equations, though, is not singular. The 
determinant, though small, does not equal zero. 
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Detecting Ill-conditioned Matrices 

Now that you’ve seen how ill-conditioning can affect the solutions to a set of simultaneous 
equations, you’re probably wondering how you can tell an ill-conditioned matrix when you see 
one. There are a number of different techniques, none of which is entirely fail-proof. Used 
together, however, they are quite dependable. 


In general, the determinant of an ill-conditioned matrix is very small compared with the ele¬ 
ments of the matrix. So one of the first steps you can take is to look at the determinant. The 
term “very small” is, of course, relative. If a matrix contained elements all greater than 1000, 
then a determinant that equaled 10 would be very small. On the other hand, if all the elements 
in an array were less than 20 then a determinant of 10 would be quite reasonable. One 
equation for determining whether the determinant is “too small” is given below: 


DET(A) 



i=i j=i 


«1 


We can execute this equation in a program as follows. 


100 FOR X =(BASE A»l) TO (SIZE A»1)+(BASE A »1)- 1 
120 FOR Y =(BASE A>2) TO (SIZE A»2)+(BASE A»2)-l 
130 Total=Total+A(X >Y)"2 

140 NEXT Y 
150 NEXT X 

ISO Test=DET(A)/SQR(Total) 

170 IF TestC.001 THEN Ill.con 


Note that line 170 can be changed depending on how much accuracy you require for your 
particular application. If we execute this program for the ill-conditioned matrix discussed earlier, 
the value of “Test” comes out to 9.527E-19. Since this value is much smaller than .001, this 
test would have correctly identified A as an ill-conditioned matrix. 

Another technique for detecting ill-conditioned matrices is to multiply the matrix by its inverse 
and compare the product with the identity matrix. Again, you can demand as much accuracy as 
necessary. In the program below, we look for any elements in the product that differ by more 
than .001 from the identity matrix. 


100 

MAT 

I = I DN 

110 

MAT 

A_inv = IIMV< A) 

120 

MAT 

Product=A-inu*A 

130 

MAT 

Differ=(Product-I) 

140 

MAT 

C o m p a r e = Dif f e r >(*001) 

150 

MAT 

Compa r e 1 = Di f f e r <(-♦001 ) 

1 GO 

IF 

SUM(Compare)+SUM(Comparel 


>0 THEN I 1 1 _ o o n 
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Applying this algorithm to our ill-conditioned matrix, we get: 

A*A_inv 

0 0 0 o~ 

0 1 -.5 0 

-2 -.5 -4 -16 
.-2 -.5 -8 -16_ 

As you can see, 12 of the 16 elements differ from the identity matrix by more than 1, so this test 
also would have worked. 

One drawback of this method is that it requires several additional matrices. If you are strapped 
for memory, this method could be unsatisfactory. 

A third technique is to take the inverse of the inverse and compare it to the original matrix. The 
program below utilizes this method. Again, we are looking for differences greater than 0.001. 


100 

MAT 

A_inv=INM<A) 

120 

MAT 

A „ i n v - i n v = IN 0 ( A i n u ) 

130 

MAT 

Differ=(A_inv-inv-A) 

140 

MAT 

C o m p a r e = Dif f e r >(*001) 

150 

MAT 

C o m p a r e1= Dif f e r<(-♦001) 

1 GO 

IF 

SUM(Compare)+SUM(Cofflparei) 


>0 THEN 111 _c on 


Applying this technique to our ill-conditioned matrix, we find that all 16 elements of 
A_ i n v _ i n v differ from A by more than .001. 


This technique will in general find more ill-conditioned matrices than the previous one. This is 
because any round-off errors are exaggerated by the second inverse. By the same token, it will 
occasionally detect an ill-conditioned matrix which might actually have been alright before the 
second inverse. 


As stated before, none of these methods alone is decisive. What it all comes down to is that the 
precision of MAT INV falls off as a matrix approaches singularity. By using combinations of the 
tests described above, it is possible to determine how much precision has been lost, and then 
compare it to the precision actually required by your application. 
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Miscellaneous Matrix Functions 

There are a few matrix functions that we haven’t discussed yet. One of these is the transpose 
function (TRN). The transpose of a matrix is derived by exchanging rows for columns and 
columns for rows. If A is the matrix below, 

A 

"l 2 3" 

4 5 6 
1 8 9_ 

then, 

MAT B = TRN(A) 
would result in: 


B 

"l 4 7" 

2 5 8 
_3 6 9_ 

A matrix does not have to be square to have a transpose. If A is, 

A 

f0 1 8 3"| 

[2 9 7-2j 

then, 

MAT B=TRN(A) 
would result in: 


B 

0 2 
1 9 
8 7 
3 -2 


The result array cannot be the same as the array being transposed. For example, 

MAT A=TRN(A) 

is an illegal statement and will cause an error. 

The transpose function is useful for manipulating tables of data. It also has special significance 
for a small set of matrices called “orthogonal” matrices. An orthogonal matrix is defined as one 
whose transpose and inverse are the same. 










116 Numeric Computation 


Summing Rows and Columns 

BASIC has two functions that return the sum of all rows and columns in an array. The totals are 
stored in a vector which you must dimension beforehand. Let A be the matrix shown below. 


A 

"3 6 18 7 

1 0 41 2 

_4 3 12 11_ 

If we execute: 

10 OPTION BASE 1 

20 DIM Row.surn(3)*Col_s um(4) 

30 MAT Row_sum=RSUM(A) 

40 MAT Col_sum=CSUM(A) 

50 PRINT "The sum of rows is"5Row_sum(*) i 

SO PRINT "The sum of columns is"5Co 1_sum(*) 5 

70 END 


The system will display: 


The sum of rows is 
The sum of columns 


34 44 30 

is 8 9 71 20 


Using Arrays for Code Conversion 

Suppose you have an input device that provides information in 8-bit ASCII code. On the other 
hand, an output device in the same system uses a non-ASCII specialized 8-bit code. Examples 
might include specialized instrumentation, typesetting equipment, or a multitude of other de¬ 
vices. For each ASCII character, there is a corresponding code for the output device. There may 
be some ASCII characters (such as control characters) that are not to be converted. Let us 
assume that a null character (all bits set to zero) is used for those special characters. Here is how 
a conversion array is set up: 

1. First, an array is created with 256 elements (0 thru 255). Each element address corres¬ 
ponds to the 8-bit INTEGER numeric equivalent of the ASCII character code. The 
contents of a given array element contains the output code for the corresponding ASCII 
input code. The array can be REAL or INTEGER. Usually, it is more efficient to use 
INTEGER arrays for converting 16-bit or shorter codes. The array must be filled by 
individual program statements (assignments or DATA and READ statements), or it can be 
filled from a mass storage file. If a file is used, the data must be created by some prior 
means. Fixed conversion codes can sometimes be generated by an algorithm in the 
introductory part of the program that performs the conversions. 

2. Input data is placed in a string variable (see Chapter 5 for string variables techniques). 
Characters are then picked off, one character at a time, for conversion. Refer to BASIC 
Interfacing Techniques for more information about output operations. 
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Here is an example of how such an operation could be implemented: 

1UUU INTEGER Conuert(0:255) 

1010 DIM In$[80] 

lu2u Source=18 ! Source device selector 

lu3u D e s t = 2 2 ! Destination device selector 


Initialize the conversion array here. 


2470 ENTER Source !Input$ ! Input line of ASCII 
2480 FOR 1 = 1 TO L E N( I n $ ) ! Send converted bytes 

2430 OUTPUT Dest5CHR$(Convert(NUM(In$[I , I ] ) ) ) 5 

2500 NEXT I 

Note that the semicolon in line 2490 prevents sending a carriage-return and line-feed character 
pair at the end of each output line. This is usually necessary to prevent unwanted behavior 
when using ASCII strings to output non-ASCII data. This technique can be applied to arbitrary 
data conversions with virtually no limitations. 

It is also possible to handle code conversions automatically in OUTPUT statements with the 
CONVERT options of the ASSIGN statement. See the ASSIGN Attributes discussion in BASIC 
Interfacing Techniques. 

For further information about the topics in this chapter, see: 

1 Coonen, Jerome T.; “An Implementation Guide to the Proposed Floating Point Standard", Computer Magazine, Jan. 1980. 

2 Cody, William J. Jr. and William Waite; Software Manual for the Elementary Functions, Prentice Hall, 1980. 

3 Sterbenz, Pat H.; Floating Point Computation, Prentice Hall, 1974. 

4 Signum Newsletter, Oct. 1979. 
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Notes 





String Manipulation 


Chapter 


Introduction 

It is often desirable to store non-numerical information in the computer. A word, a name or a 
message can be stored in the computer as a string. Any sequence of characters may be used in 
a string. Quotation marks are used to delimit the beginning and ending of the string. The 
following are valid string assignments. 

LET A$="COMPUTER" 

Fail$="The test has failed." 

Fi1e_name$="INVENTORY" 

Test$=Fail$[5>8] 

The left-hand side of the assignment (the variable name) is equated to the right-hand side of the 
assignment (the literal). 


String variable names are identical to numeric variable names with the exception of a dollar sign 
($) appended to the end of the name. 

The length of a string is the number of characters in the string. In the previous example, the 
length of A$ is 8 since there are eight characters in the literal “COMPUTER”. 

BASIC allows the dimensioned length of a string to range from 1 to 32 767 characters and the 
current length (number of characters in the string) to range from zero to the dimensioned 
length. A string of zero characters is often called a null string or an empty string. 

The default dimensioned length of a string is 18 characters. The DIM, COM, and ALLOCATE 
statements are used to define string lengths up to the maximum length of 32 767 characters. An 
error results whenever a string variable is assigned more characters than its dimensioned length. 

A string may contain any character. The only special case is when a quotation mark needs to be 
in a string. Two quotes, in succession, will embed a quote within a string. 

10 Q u o t e $ = " T h e time is ""NOW""." 

20 PRINT Quo t e$ 

30 END 


Produces: The time is "NOW". 
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String Storage 

Strings whose length exceeds the default length of 18 characters must have space reserved 
before assignment. The following statements may be used. 

• DIM Lons$C400] Reserve space for a 400 character string. 

• COM L i n e $ 180 ] Reserve an 80 character common variable. 

• ALLOCATE Se a rch$C Ler. at h ] Dynamic length allocation. 

The maximum length of any string must not exceed 32 767 characters. A string may also be 
dimensioned to a length less than the default length of 18 characters. 

The DIM statement reserves storage for strings. 

DIM Part_nurnbe r$C101 >Dec ri>tion$[841 >Cost$C5] 

The COM statement defines common variables that can be used by subprograms. 

COM Name$C40] »Ph on e$[14] 

The ALLOCATE statement allows dynamic allocation of string storage. When the maximum 
length of a string cannot be determined ahead of time, the ALLOCATE statement can be used 
to reserve enough memory space for the string without wasting space. 

ALLOCATE L i n e $ C Len sf t h ] 

Strings that have been dimensioned but not assigned return the null string. 

String Arrays 

Large amounts of text are easily handled in arrays. For example. 

DIM File$(1000)C80] 

This statement reserves storage for 1000 lines of 80 characters per line. Do not confuse the 
brackets, which define the length of the string, with the parentheses which define the number of 
strings in the array. Each string in the array can be accessed by an index. For example. 

PRINT Fi 1 e$(27) 

Prints the 27th element in the array. Since each character in a string uses one byte of memory 
and each string in the array requires as many bytes as the length of the string, string arrays can 
quickly use a lot of memory. 

A program saved on a disc as an ASCII type file can be entered into a string array, manipulated, 
and written back out to disc. 
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Evaluating Expressions Containing Strings 

Evaluation Hierarchy 

Evaluation of string expressions is simpler than evaluation of numerical expressions. The three 
allowed operations are extracting a substring, concatenation, and parenthesization. The evalua¬ 
tion hierarchy is presented in the following table. 


Order 

Operation 

High 

Parentheses 

- 

Substrings and Functions 

Low 

Concatenation 


String Concatenation 

Two separate strings are joined together by using the concatenation operator “6:”. The follow¬ 
ing program combines two strings into one. 

10 0ne$ ="WRIST" 

20 Two$="WATCH" 

30 Concat$ = 0ne$&:Two$ 

40 PRINT 0ne$ »Two$ >Coricat$ 

50 END 

Prints: 

WRIST WATCH WRISTWATCH 

The concatenation operation, in line 30, appends the second string to the end of the first string. 
The result is assigned to a third string. An error results if the concatenation operation produces a 
string that is longer than the dimensioned length of the string being assigned. 

Relational Operations 

Most of the relational operators used for numeric expression evaluation can also be used for the 
evaluation of strings. 

The following examples show some of the possible tests. 


ABC" = "ABC" 

True 

ABC" = " ABC" 

False 

ABC" < " A b C" 

True 

G " > " 7 " 

False 

*7 ii ^ ii i ii 

False 

lonS " < = "longer " 

True 

RE-SAVE" >= "RESAVE" 

False 


Any of these relational operators may be used: <,>,< = ,> = , =, <>. 

Testing begins with the first character in the string and proceeds, character by character, until 
the relationship has been determined. 
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The outcome of a relational test is based on the characters in the strings not on the length of the 
strings. For example: 

"BRONTOSAURUS" < "CAT" 

This relationship is true since the letter “C” is higher in ASCII value than the letter “B”. 


Note 

When LEX is loaded, the outcome of a string comparison is based on 
the character’s lexical value rather than the character’s ASCII value. See 
the LEXICAL ORDER IS statement later in this chapter for more details. 


Substrings 

A subscript can be appended to a string variable name to define a substring. A substring may 
comprise all or just part of the original string. Brackets enclose the subscript which can be a 
constant, variable, or numeric expression. For instance: 

String$[4] Specifies a substring starting with the fourth character of the ori¬ 

ginal string. 

The subscript must be in the range: 1 to the dimensioned length of the string plus 1. Note that 
the brackets now indicate the substring’s starting position instead of the total length of the string 
as when reserving storage for a string. 

Subscripted strings may appear on either side of the assignment. 

Single-Subscript Substrings 

When a substring is specified with only one numerical expression, enclosed with brackets, the 
expression is evaluated and rounded to an integer indicating the position of the first character of 
the substring within the string. 

The following examples use the variable A$ which has been assigned the literal “DIC¬ 
TIONARY”. 


Statement 

Output 

PRINT A$ 

DICTIONARY 

PRINT A$[0] 

(error) 

PRINT A$[l] 

DICTIONARY 

PRINT A$[5] 

IONARY 

PRINT A$[10] 

Y 

PRINT A$[ll] 

(null string) 

PRINT A$[12] 

(error) 


When a single subscript is used it specifies the starting character position, within the string, of 
the substring. An error results when the subscript evaluates to zero or greater than the current 
length of the string plus 1. A subscript that evaluates to 1 plus the length of the string returns the 
null string ("") but does not produce an error. 
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Double-Subscript Substrings 

A substring may have two subscripts, within brackets, to specify a range of characters. When a 
comma is used to separate the items within brackets, the first subscript marks the beginning 
position of the substring, while the second subscript is the ending position of the substring. The 
form is: A$[Start,End] 

“JABBERWOCKY”[4,6] Specifies the substring: “BER” 

When a semicolon is used in place of a comma, the first subscript again marks the beginning 
position of the substring, while the second subscript is now the length of the substring. The form 
is: A$[Start;Length] 

“JABBERWOCKY”[4;6] Specifies the substring: “BERWOC” 

In the following examples the variable B$ has been assigned to the literal “ENLIGHTEN¬ 
MENT”: 


Statement 

Output 

PRINT B$ 

ENLIGHTENMENT 

PRINT B$[ 1,13] 

ENLIGHTENMENT 

PRINT B$[l;13] 

ENLIGHTENMENT 

PRINT B$[l,9] 

ENLIGHTEN 

PRINT B$[l;9] 

ENLIGHTEN 

PRINT B$[3,7] 

LIGHT 

PRINT B$[3;7] 

LIGHTEN 

PRINT B$[13,13] 

N 

PRINT B$[13;l] 

N 

PRINT B$[13,26] 

(error) 

PRINT B$[13;13] 

(error) 

PRINT B$[14;l] 

(null string) 


An error results if the second subscript in a comma separated pair is greater than the current 
string length plus 1 or if the sum of the subscripts in a semicolon separated pair is greater than 
the current string length plus 1. 

Specifying the position just past the end of a string returns the null string. 


Special Considerations 

All substring operations allow a subscript to specify the first position past the end of a string. 
This allows strings to be concatenated without the concatenation operator. For instance: 



10 

20 

30 

40 


A$ ="CONCAT" 
A$C7]="ENATION" 
PRINT A* 

END 


Produces: CONCATENATION 
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The substring assignment is only valid if the substring already has characters up to the specified 
position. Access beyond the first position past the end of a string results in the error: 

ERROR 18 Strin 3 oufl. or substring err 

A good practice is to dimension all strings including those shorter than the default length of 
eighteen characters. 

Some very interesting assignments can be attempted. For example, a 14-character string can be 
assigned to a 3-character substring. 

10 Bis*="Too bis to fit" 

20 Small$="Little strinS" 

30 ! 

40 Sma11 $[1 ,33=BiS* 

50 ! 

GO PRINT Small* 

70 END 

Prints: Tootle s t r i n 3 

When a substring assignment specifies fewer characters than are available, any extra trailing 
characters are truncated. 

The alternate assignment is shown in the next example. Here a 4-character string is assigned to 
a 8-character substring. 

10 Bis*="A larSe strinS" 

20 Small*="tiny" 

30 ! 

40 B i S * [ 3 »103=Small* 

50 ! 

GO DISP Bis* 

70 END 

Prints: ft tiny r i n 3 

Since the subscripted length of the substring is greater than the length of the replacement string, 
enough blanks (ASCII spaces) are added to the end of the replacement string to fill the entire 
specified substring. 
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String-Related Functions 

Several intrinsic functions are available in BASIC for the manipulation of strings. These func¬ 
tions include conversions between string and numeric values. 

String Length 

The “length” of a string is the number of characters in the string. The LEN function returns an 
integer whose value is equal to the string length. The range is from 0 (null string) thru 32 767. 
For example: 

PRINT LEN("HELP ME" ) 

Prints: 7 

The following example program prints the length of a string that is typed on the keyboard. 

10 DIM In*[1603 

20 INPUT In* 

30 LenSth=LEN(In*) 

40 DIS P Length 5"characters in " " " 51 n $ 5"""" 

50 END 


Try finding the length of a string containing only spaces. When the INPUT statement is used, 
any leading or trailing spaces are removed from items typed on the keyboard. Change INPUT 
to LINPUT in line 20 to allow leading and trailing spaces to be entered. 


Substring Position 

The “position” of a substring within a string is determined by the POS function. The function 
returns the value of the starting position of the substring or zero if the entire substring was not 
found. For instance: 

PRINT P0S<"DISAPPEARANCE"t"APPEAR") 

Prints: 4 

The following example prints the positions of substrings found within a string. 

10 DIM Sentence*[403 ,Word*(1:6)C83 
20 DATA CAT i0N »A tHOT (TIN (NATION 

30 READ Wo rd*(*) 

40 Sentence*="WHERE IS THE CAT IN C0NCATI NAT I ON" 

50 ! 

GO FOR 1=1 TO 6 

70 Position =POS(Sentence$>Word$(I)) ! <- POS function 

80 IF Position THEN 

90 PRINT Sentence$ 

100 PRINT TAB(Position) 5 Wo rd$(I ) 5 TAB(35) 5"is at ".Position 

110 PRINT 

120 ELSE 

130 PRINT " ' " 5 W o r d $ ( I ) 5" ' was not found" 

140 PRINT 

150 END IF 

ISO NEXT I 

170 END 


If POS returns a non-zero value, the entire substring occurs in the first string and the value 
specifies the starting position of the substring. 
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Note that POS returns the first occurrence of a substring within a string. By adding a subscript, and 
indexing through the string, the POS function can be used to find all occurrences of a substring. The 
following program uses this technique to extract each word from a sentence. 


10 

DIM A $ C 8 0] 





20 

A $ ="I Know you t h i n K you understand 

what I s a i d ♦ 

but you don 

't ♦ " 

30 

INTEGER Scan tFound 





40 

Scan=l ! 

Current subs 

t r i n * f 

a o s i t i 

on 

50 

PRINT A$ 





GO 

REPEAT 





70 

Found = POS(A$CScan] ♦" ") ! 

Find the nex 

t ASCI] 

[ spac 

e 

80 

IF Found THEN 





90 

PRINT A$[Scan ♦Scan + Found-1] ! 

Print the wo 

rd 



100 

S c a n = S c a n + F o u n d ! 

Adjust "Scan 

" past 

last 

match 

110 

ELSE 





120 

PRINT A $ C S c a n] ! 

Print last w 

o rd in 

s t r i n 

4 

130 

END IF 





140 

UNTIL NOT Found 





150 

END 






As each occurrence is found, the new subscript specifies the remaining portion of the string to 
be searched. 

String-to-Numeric Conversion 

The VAL function converts a string expression into a numeric value. The string must evaluate to 
a valid number or error 32 will result. 

ERROR 32 String is not a valid number 

The number returned by the VAL function will be converted to and from scientific notation 
when necessary. For example: 

PRINT UAL("123.4E3") 


Prints: 123400 


The following program converts a fraction into its equivalent decimal value. 

10 INPUT "Enter a fraction ( i ♦ e ♦ 3/4)" ♦Fraction$ 

20 ! 

30 ON ERROR GOTO Err 

40 Nurne r a t o r = 0AL(F r ac tion$) 

50 ! 

GO IF P0S(Fract iori$ ♦"/" ) THEN 

70 Delimite r=POS<Fraction$♦"/") 

80 Den omin at o r = UAL(F rac tion$C De1imit e r+13) 

90 ELSE 

100 PRINT "Invalid fraction" 

110 GOTO Quit 

120 END IF 

130 ! 

140 PRINT Fraction$5" = "iNumerator/Denominator 

150 GOTO Quit 

ISO Err: PRINT "ERROR Invalid fraction" 

170 OFF ERROR 

180 Quit; END 


Similar techniques can be used for converting: feet and inches to decimal feet or hours and 
minutes to decimal hours. 
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The NUM function converts a single character into its equivalent numeric value. The number 
returned is in the range: 0 to 255. For example: 

PRINT NUM("A") 

Prints: B5 


The next program prints the value of each character in a name. 


10 

INPUT "Enter your first 

name" t N a m e $ 

20 

! 


30 

PRINT Name$ 


40 

PRINT 


50 

FOR 1 = 1 TO LEN < Name$) 


GO 

PRINT NUM(Name$[I])5 

! Print value 

70 

NEXT I 


80 

PRINT 


90 

END 



Entering the name: JOHN will produce the following. 

74 73 72 78 

Numeric-to-String Conversion 

The VAL$ function converts the value of a numeric expression into a character string. The 
string contains the same characters (digits) that appear when the numeric variable is printed. 
For example: 

PRINT 1000000 #0AL$(1000000) 

Prints: l.E+B l.E+6 

The next program converts a number into a string so the POS function can be used to seperate 
the mantissa from the exponent. 


10 CONTROL 2 .Oil ! CAPS LOCK ON 

20 INPUT "Enter a number with an exponent"*Number 
30 ! 

40 Numbe r$=UAL$(Number) 

50 ! 

BO PRINT Numbe r$ 

70 E = POS(Numbe r$>"E") 

80 IF E THEN 

90 PRINT "Mantissa is"*Number$Cl5E-13 

100 PRINT "Exponent is"»Number$CE+1] 

110 ELSE 

120 PRINT "No exponent" 

130 END IF 

140 END 


The CHR$ function converts a number into an ASCII character. The number can be of type 
INTEGER or REAL since the value is rounded, and a modulo 255 is performed. For example: 

PRINT CHR$(37) 5CHR$(38) ;CHR$(93) 


Prints: a b c 
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The next program prints the values in the data statement as characters. 


10 

PRINT CHR$(12) ! 

CLEAR SCREEN 

20 

PRINT CHR$(7) ! 

RING THE BELL 

30 

! 


40 

DATA 34*130*89*111 

*117 *32 *103 *111 *1 IB *32 *105 *1 IB *33 *128 *34 

50 

INTEGER N(1:15) 


BO 

READ N(*) 


70 

FOR 1=1 TO 15 


80 

PRINT CHR$(N(I)) 

5 

90 

NEXT I 


100 

PRINT CHR$(7) 


110 

END 


CRT 

Character Set 



The following program prints the character set on the screen of the CRT. 


10 

20 

30 
40 
50 
BO 
70 
80 
90 
100 
110 
120 
130 
140 
150 
160 
170 
180 
190 
200 
210 
220 
230 
240 
250 
2B0 
270 
280 


! Program: CRT Character Set* 

i 

PRINT CHR$(12)5"CRT Character Set" 

STATUS l*95Line_lenSth ! 50 or 80 Column 
Left=Line_lenSth/2-lS 

j 

FOR 1=0 TO 255 

Co 1 = I MOD 1S*2 + L e f t 
R o w = I DIO 1S + 3 
IF Co 1=Le f t THEN 

PRINT TABXY(Left-5*Row)5 
PRINT USING "3D"51 
END IF 

PRINT T A B X Y(Col >Rou) 5 

CONTROL 1*451 ! Display Functions on 

PRINT CHR$(I)5 ! PRINT the Character 

CONTROL 1*450 ! Display Functions off 

NEXT I 
PRINT 
1 = 127 

ON KNOB *08 GOSUB Chansfe 

DISP USING "5A *5D »X *2A *B *B"5"ASCII"* I*" = "»128 * I 
GOTO 220 

Char.Se: I = I-KN0BX/10 

IF I<0 THEN 1=0 
IF I>255 THEN 1=255 
RETURN 

END 


ASCII character values from 128 to 159 are treated differently by different systems. Refer to the 
section “The Extended Character Set” found later in this chapter. 
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String Functions 


String Reverse 

The REV$ function returns a string created by reversing the sequence of characters in the given 
string. 

PRINT REV$("Snack cans") 

Prints: snac kcanS 

A common use for the REV$ function is to find the last occurrence of an item in a string. 


10 

DIM List*C303 


20 

Lis t$="3.22 4.33 1.10 8.55 12.20 1.77" 


30 

LenSth=LEN(List$) 


40 

Last_space=P0S(RE0$(List$) >" ") ! "SPACE" 

is delimiter 

50 

DISP "The last item i s : " i L i s t $ C 1+Ler. St h-Las t 

_space3 

B0 

END 



Displays: The last item is: 1.77 

String Repeat 

The RPT$ function returns a string created by repeating the specified string, a given number of 
times. 

PRINT RPT$("* *">10) 


Prints: * ** ** ** ** ** ** ** ** ** * 

Here is a short program that uses RPT$ to create an image for a formatted print statement. 


10 11 e ms = 7 

20 DATA 50 »900 »2 »444 >37 »2001 *32768 
30 ALLOCATE Array(1:Items) 

40 READ A r ray(*) 

50 FOR 1=1 TO Items 

B0 DiSits=INT( 1+LGT( Array(I))) 

70 IF Dibits>Maxditfits THEN MaxdiSits=DiSits 

80 NEXT I 

90 Fo rm$ = " XX *"&RPT$ < " D" tMaxd i i t s ) ♦ DD" 

100 PRINT "Usin* the imaSe: "5Form$ 

110 PRINT USING Fo rm$ 5 A r ray(*) 

120 END 


Trimming a String 

The TRIMS function returns a string with all leading and trailing blanks (ASCII spaces) re¬ 
moved. 

PRINT 5TRIM$<" 1.23 ")5"*" 


Prints: *1.23* 





130 String Manipulation 


TRIMS is often used to extract fields from data statements or keyboard input. 


10 INPUT "Enter your full riame 11 »Name* 

20 First*=TRIM*(Name*£1 ,P0S(Name*")]) 

30 Last*=TRIM*(Name$Cl+LEN(Name$)-POS(REO*(Name*)t" ")1) 

40 PRINT Name! iLEN(Name*) 

50 PRINT Last* .LEN<Last*> 

GO PRINT Fi rst* »LEN(First*) 

70 END 

Note that the INPUT statement trims leading and trailing blanks from whatever is typed. If you 
need to enter leading or trailing spaces, use the LINPUT statement. 


Case Conversion 

The case conversion functions, UPC$ and LWC$, return strings with all characters converted to 
the proper case. UPC$ converts all lowercase characters to their corresponding uppercase 
characters and LWC$ converts any uppercase characters to their corresponding lowercase 
characters. Roman Extension characters will be converted according to the current lexical 
order. See the LEXICAL ORDER IS statement later in this chapter for the case conversion 


listings. 



10 

DIM Word$[1603 


20 

LINPUT "Enter a few 

characters"» W o r d $ 

30 

PRINT 


40 

PRINT "You typed: " 

5 W o r d $ 

50 

PRINT "Uppercase: " 

5UPC$(Wo rd$) 

B0 

PRINT "Lowercase: " 

5LWC$ (Wo rd$) 

70 

END 



A more general character replacement method is obtained by using a buffer that was assigned 
an indexed conversion. Indexed conversion uses the incoming character’s ASCII value as an 
index into a string of characters and returns the character in that position. In the following 
program, the conversion string is created in lines 30 and 50. The conversion string specifies all 
lowercase characters are to be replaced by their corresponding uppercase character. 


10 

DIM Ciphe r$C25B] »A$C803 


20 

FOR 1=1 TO 255 

! Create conversion 

30 

Ciphe r$ = Ciphe r$&:UPC$(CHR$( I ) ) 


40 

NEXT I 


50 

Ciphe r$ = Ciphe r$&=UPC$ < CHR$ < 0)) 


B0 

ASSIGN @F TO BUFFER C1B03 5 CONVERT 

OUT BY INDEX Cipher$ 

70 

LOOP 


80 

INPUT A$ 


90 

OUTPUT @F 5 A$ 

! Conversion occurs 

100 

ENTER @F5A$ 


110 

PRINT A$ 


120 

END LOOP 


130 

END 
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Searching and Sorting 

Information stored in a string array often requires sorting. There are over a dozen common 
algorithms that may be used. Each alogrithm has certain advantages depending on the number 
of items to be sorted, the current order of the items, the time allowed to sort the items, and the 
complexity of the algorithm. One of the simplest (and most inefficient) sorts to implement is the 
“bubble” sort. The following program is a slight variation of the bubble sort. 


10 ! Program: SORT 

20 ! 

30 READ N 

40 DATA 10 ! NUMBER OF ITEMS TO SORT 

50 ALLOCATE Word$(N)C5] .Temp*[53 
60 READ Wo rd$(#) ! READ ENTIRE ARRAY 

70 DATA zero tone >two »three *four»fiue »six tseuen t e i sf h t »nine >ten 

80 PRINT Wo rd$(#) 

90 PRINT 

100 SortsFOR 1=0 TO N-l 

110 IF Wo rd$(I)>Wo rd$(1 + 1) THEN 

120 Temp$ = Wo rd$(I) 

130 Wo rd$<I)=Word$<1 + 1) 

140 Wo rd$ <1 + 1)= Temp$ 

150 GOTO Sort 

ISO END IF 

170 NEXT I 

180 PRINT Wo rd$(#) 

190 END 


This example prints the contents of the array before and after sorting. 
Before sorting: 


zero 

on e 

two 

three 

four 

f iue 

six 

seue n 

e i 3h t 

n i n e 

ten 


After sorting: 

e i 3h l 

five 

four 

n i n e 

on e 

seue n 

six 

ten 

three 

two 

zero 



The strings are sorted in ascending order. If the relational operator in line 110 is changed from 
the greater than sign “>” to the less than sign “<”, the strings will be sorted in descending 
order. 
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MAT Functions and String Arrays 

MAT functions (available with MAT) are commonly used to manipulate data in numeric arrays. 
However, several of these functions can be used with string arrays. For example, a string array is 
copied into another string array by the following. 

MAT Cop'/$ = Original* 

Note that only the variable name is necessary. The array specifier “ ( * ) ” need not be included 
when using the MAT statement. 

Every element in a string array will be initialized to a constant value by the following statement. 
MAT Array* = <Null$) 


The constant value can be a literal or a string expression and is enclosed in parentheses to 
distinguish it from being an array name. 

A list of items can be sorted very quickly by the MAT SORT statement. 


10 

! Pro 

sfram: S0RT_L 

1ST 

20 

DIM L 

is t$(1:5)EG] 


30 

DATA 

Bread t Mi1K»E 

33s rBacon tCoffee 

ao 

READ 

List$(*) 


50 

! 



GO 

PRINT 

"original o 

rder" 

70 

PRINT 

L i s t $ ( # ) 


80 

! 



90 

PRINT 

"ascendin 3 

order" 

100 

MAT SORT Lis t$(*) 


110 

PRINT 

L i s t $ ( * ) 


120 

! 



130 

PRINT 

" d e s c e n d i n a 

order" 

140 

MAT SORT Lis t $(*) 

DES 

150 

PRINT 

L i s t $ ( * ) 


1 GO 

END 




Running this program produces: 
original order 

Bread Milk E3Ss Bacon Coffee 

ascending order 

Bacon Bread Coffee Eggs Milk 

descending order 
Milk Eggs 


Coffee 


Bread 


Bacon 
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Sorting by Substrings 

A substring range can be appended to the end of a MAT SORT statement. Items will then be 
sorted by the characters within the substring specified. No error results from specifying a 
substring position beyond the current length of the string. 


10 PRINT CHR$(12) ! Program: SUBSORT 

20 DATA 1 OLD ORANGE#2 TINY TOADS »3 TALL TREES>4 FAT FOWLS»5 FRIED FISH 

30 DATA B SLOW SNAILS >7 SLIMY SLUGS >8 AWFUL HOURS>9 NASTY KNIVES 

40 DIM Thin*$<1:9)C383 
50 READ Thinsr$(*) 

SO First=l 

70 Len at h = 1 

80 DISP "Use KNOB and SHIFT-KNOB to change sort field*" 

SO ON KNOB ♦15 GOTO Slide 

100 GosMAT SORT Th i n *$ ( * ) C F i rs t 5 Ler. * t h 3 

110 FOR 1=1 TO S 

120 PRINT TABXY(10>I)5Thins$(I)5" 

130 NEXT I 
140 W:GOTO W 
150 ! 

ISO Slide: ! 

170 S=SGN(KNOBY) 

180 H=SGN(KNOBX) 

190 IF S THEN 

200 Len*th=Len*th+S*(S>0 AND Len * t h< 18 ) +S* ( S< 0 AND Len*th>l) 

210 END IF 

220 IF H THEN 

230 First=First+H*(H>0 AND First<18)+H*<H<0 AND First>l) 

240 END IF 

250 DISP "MAT SORT Thin$$(*)["5 First !"5"5Lenath5"3" 

2G0 PRINT T A B X Y ( 9 »1 0 ) 5 R P T $(" " »First) 5RPT$(" A " »Len 3 1h) »RPT$(" "»10) 

270 GOTO Go 

280 END 


Adding Items to a Sorted List 

Lists of strings can be maintained in sorted order. Every time a new item is added to the list, the 
list is sorted by the MAT SORT statement. To prevent overwriting any of the items already in 
the list, items should be added to the top (first array element) of a list sorted in ascending order 
and to the bottom (last array element) of a list sorted in descending order. 


10 

20 

30 

40 

50 

GO 

70 

80 

90 

100 

110 

120 

130 

140 

150 

180 

170 

180 

190 

200 

210 

220 

230 


PRINT CHR$(12) 

! Since arrays are in COM t they "remember" old values* 

! After running execute SCRATCH C to clear the arrays* 

! 

COM Ascend$(l:18)[183»Descend$(l:18)C183 
Atfain:1=1+1 

INPUT "Enter a word"»Word$ 

Ascend$(l)=Word$ ! Fill array at top 

Descend$(18)=Word$ ! Fill array at bottom 

CALL See 

IF I<18 THEN ASain 

BEEP 

END 

! _ 

SUB See ! DISPLAY THE ARRAYS 

COM Ascend$(*) »Descend$(*) 

MAT SORT Ascend$ ! <- ascend in sf sort 

MAT SORT Descend! DES ! <- descending sort 

FOR J=1 TO 18 

PRINT TABXY(1 #J> !RPT$(" "»49> 

PRINT T ABXY ( 1 tJ) 5 J 5 T ABXY ( 11 »J ) i Ascend.* < J) 5TABXY(31 »J)5Descer«d$(J) 
NEXT J 
SUBEND 
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Sorting by Multiple Keys 

When sorting a multi-dimension array, it is possible to specify more than one key. The array will 
be sorted by the first key then the second key and so on until the key specifiers are exhausted. 
Once the first key sorts items into similar groups, the items within a group can be arranged in 
any order you choose. 


10 COM Too 1 $(1:8 >1:3> CIO] 

20 DATA PENCIL .RED .35 .PENCIL .BLUE .12 .PENCIL .GREEN .0 .PENCIL .BLACK .17 
30 DATA PEN .BLACK .17 .PEN .BLUE .127 .PEN .RED .55 .PEN .GREEN .43 
40 READ Too1 $(*) 

50 PRINT 

60 PRINT "*** UNSORTED LIST ***" 

70 Display 

80 PRINT "*** SORT BY COLOR ***" 

90 MAT SORT Too 1$<*#2>[1 *33 ! Sort color by first three letters* 

100 Display 

110 PRINT "*** SORT BY COLOR THEN BY NAME ***" 

120 MAT SORT Too1 $(* »2) »(*»!) ! Two key sort. 

130 Display 

140 PRINT "*** SORT BY NAME THEN BY COLOR ***" 

150 MAT SORT Too 1$<*#1> »<*»2>C1533 DES 
ISO Display 

170 END 

180 !- 

190 SUB Display 
200 COM Too1 $(*) 

210 K = K +1 

220 FOR 1=1 TO 8 

230 FOR J=1 TO 3 

240 PRINT Too1 $( I »J) ♦ 

250 NEXT J 

290 PRINT 

270 NEXT I 

280 SUBEND 


Sorting to a Vector 

It is possible to determine the sorting order of items in an array without disturbing the array. 
This is accomplished by “sorting” to a single-dimensioned numeric array (vector). The vector 
will then contain the subscripts of the items in the order that the items would have been 
arranged. 

10 DIM Month*(1:12)C3] .Fix( 

20 DATA JAN .FEB .MAR .APR .MAY 
30 READ Mon t h*(*) 

40 MAT SORT Month* TO Fix 

50 PRINT Month*(*) 

60 PRINT Fix(*) 

70 FOR 1=1 TO 12 

80 PRINT Month*(Fix( I ) ) t 

90 NEXT I 

100 END 

Running this program produces: 

JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC 

4 8 12 2 1 7 G 3 5 11 10 9 

APR AUG DEC FEB JAN JUL JUN MAR MAY NOV OCT SEP 

The first element of the vector contains a four (4), indicating the fourth element in the array 
would be the first element if the array were actually sorted. 


1 : 12 ) 

.JUN .JUL .AUG ,SEP .OCT .NOU .DEC 
! Sort to vector 


! Print months alphabetically 
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Reordering an Array 

The rows and columns of multiple dimension arrays can be reordered. Reordering is made 
according to a reorder vector (single dimension array). The vector contains the values of the 
subscripts of the array. When the array is reordered, the columns (or rows) are arranged 
according to the the order of the subscripts in the reorder vector. See the following program for 
an example of reordering. 


10 PRINT CHR$(12)i ! SORT-DEMO 

20 DIM Size*<0: 1 ) C5] .Color$(0:2) 151 .Shape*<0:1)[51 

30 COM Ident$(0:3)C5] )Array$(0:3»0:ll)CG] >0 rd e r(0:3) .Field .Down 

40 DATA COUNT(SIZE .COLORtSHAPE 

50 DATA small»lar0e»blue»red»dreen»cube»ball»l»2»3»0 

GO READ Ident$(*) »Size$(*) »Co1or$(*) »Shape$(*) #0rder(*) 

70 FOR 1=0 TO 11 

80 A r ray $ ( 0 »I )=RPT$< " " »I<9)&cMAL$( 1 + 1 ) 

90 Array$(1»I)=Size$(I DIM G) 

100 Array$(2 > I)=Color$(I DIM 2 MOD 3) 

110 Array$(3»I)=Ghape$(I MOD 2) 

120 NEXT I 

130 ON KBD CALL Do-key 

140 A*ain:D$=" Ascending" 

150 IF Down THEN D$="Descending" 

1 GO DIGP D$ 5" sort on field #"5Field+l 

170 Sort 

180 Display 

190 GOTO Atfain 

200 END 

210 !- 

220 SUB Display 

230 COM Ident$(*)»Array$(*)»Order(*) »Field»Down 

240 PRINT TABXY(1 >1) 5 

250 PRINT "Press: A for ascend in* sort" 

2G0 PRINT " D for descending sort" 

270 PRINT " R to reorder array" 

280 PRINT " 1-4 for sort field"5TABXY(1»5) 

290 PRINT USING "# »3X #5A"51 dent$(#) 

300 FOR 1=0 TO 11 

310 PRINT TABXY(1 *1+7) » 

320 FOR J=0 TO 3 

330 PRINT USING "#»3X»5A"5Array$(J»I) 

340 NEXT J 

350 NEXT I 

3G0 SUBEND 

370 !- 

380 SUB Sort 

390 COM Ident$(*)»Array$(#)»Order(#) 'Field »D o w n 

400 IF Down THEN 

410 MAT SORT A r ray$(Field #*) DES 

420 ELSE 

430 MAT SORT Array$(Field »*) 

440 END IF 

450 SUBEND 

4G0 !- 

470 SUB Do_key 

480 COM Ident$(*)»Array$(*)>Order(*) 'Field»Down 

490 Key$=KBD$ 

500 SELECT Key$ 

510 CASE "1" TO "4" 

520 Field=MAL(Key$)-l 

530 CASE "A" '"a" 

540 Down=0 

550 CASE "D"»"d" 

5G0 Down=l 







146 String Manipulation 


Lexical Tables 

The following tables show the five predefined lexical orders available with the LEXICAL 
ORDER IS statement. 

Notation 

All of the lexical tables use the following notation. 


sequence number —> 

113 

character displayed —*■ 

a 

ASCII value —*■ 

(97) 


Characters not available on the keyboard can be entered by pressing the [ANY CHAR) key and 
typing the value enclosed in parentheses (with leading zeros, if needed). The character will be 
collated according to the sequence number shown above the character. 

ASCII Lexical Order 

The ASCII lexical order uses the character’s ASCII value as the sequence number. There are no 
special cases (mode table entries) used in the ASCII lexical order. 

Case Conversions 

The following lists show the UPC$ and LWC$ transformations for the ASCII lexical order. 

UPC$ 

abcdefghi j k lmnopqrstuvwxyzjnaeouaeouaeouaeouiai'BJM l'Badosyk 
flBCDEFGHIJKLMNOPQRSTUVWXYZQNAEOUAEOUAEOUAEOuiAiaitiiBftDosvf 
LWC$ 

ABCDEFGHIJKLMNOPQRSTUVWXYZaaeee iiuuQNABitAOGEOAfiDiiooosuvt 
abcdefghi j k1mnopqrstuvwxy zaaeee ii uu^naecaoueoaadi i 665 suy ► 


Note 

There are slight variations in the operation of the UPC$ and LWC$ 
functions depending on the lexical order in effect. In other words, the 
lexical order determines which character will be returned by the 
UPC$ and LWC$ functions. The case conversion lists show which 
characters should be expected for each lexical order. To simplify the 
lists, characters not affected have been excluded. 
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LEXICAL ORDER IS ASCII 


Seq. 

Chr 

Num. 

Seq. 

Chr 

Num. 

Seq. 

Chr 

Num. 

Seq. 

Chr. Nam. 

Seq. 

Chr. Nam. 

0 

N 

u 

(0) 

52 

4 

(52) 

104 

h 

(104) 

156 

9 

c 

(156) 

208 

A 

(208) 

1 

5 

H 

(1) 

53 

5 

(53) 

105 

i 

(105) 

157 

9 

D 

(157) 

209 

1 

(209) 

2 

5 

X 

(2) 

54 

6 

(54) 

106 

j 

(106) 

158 

9 

E 

(158) 

210 

0 

(210) 

3 

E 

X 

(3) 

55 

7 

(55) 

107 

k 

(107) 

159 

9 

F 

(159) 

211 

A 

(211) 

4 

E 

T 

(4) 

56 

8 

(56) 

108 

1 

(108) 

160 


(160) 

212 

a 

(212) 

5 

E 

0 

(5) 

57 

9 

(57) 

109 

ro 

(109) 

161 

k 

(161) 

213 

i 

(213) 

6 

A 

K 

(6) 

58 

: 

(58) 

110 

n 

(110) 

162 

k 

(162) 

214 

0 

(214) 

7 

0 

(7) 

59 


(59) 

111 

o 

(111) 

163 

£ 

(163) 

215 

3B 

(215) 

8 

B 

5 

(8) 

60 

< 

(60) 

112 

P 

(112) 

164 

£ 

(164) 

216 

A 

(216) 

9 

H 

T 

(9) 

61 

= 

(61) 

113 

q 

(113) 

165 

£ 

(165) 

217 

1 

(217) 

10 

L 

F 

(10) 

62 

> 

(62) 

114 

r 

(114) 

166 

t 

(166) 

218 

o 

(218) 

11 

V 

T 

(11) 

63 

? 

(63) 

115 

s 

(115) 

167 

X 

(167) 

219 

0 

(219) 

12 

F r 

(12) 

64 

0 

(64) 

116 

t 

(116) 

168 

* 

(168) 

220 

£ 

(220) 

13 

C 

R 

(13) 

65 

A 

(65) 

117 

u 

(117) 

169 


(169) 

221 

i 

(221) 

14 

1 

(14) 

66 

B 

(66) 

118 

V 

(118) 

170 

" v 

(170) 

222 

3 

(222) 

15 

5 

I 

(15) 

67 

C 

(67) 

119 

w 

(119) 

171 


(171) 

223 

b 

(223) 

16 

D 

L 

(16) 

68 

D 

(68) 

120 

X 

(120) 

172 


(172) 

224 

k 

(224) 

17 

D i 

(17) 

69 

E 

(69) 

121 

Y 

(121) 

173 

0 

(173) 

225 

k 

(225) 

18 

% 

(18) 

70 

F 

(70) 

122 

z 

(122) 

174 

0 

(174) 

226 

A 

(226) 

19 

S 

(19) 

71 

G 

(71) 

123 

< 

(123) 

175 

€ 

(175) 

227 

D 

(227) 

20 


(20) 

72 

H 

(72) 

124 

1 

(124) 

176 


(176) 

228 

d 

(228) 

21 

N 

K 

(21) 

73 

I 

(73) 

125 

> 

(125) 

177 

B 

1 

(177) 

229 

1 

(229) 

22 

5 

Y 

(22) 

74 

J 

(74) 

126 

- 

(126) 

178 

B 

2 

(178) 

230 

± 

(230) 

23 

E 

B 

(23) 

75 

K 

(75) 

127 

I 

(127) 

179 

* 

(179) 

231 

6 

(231) 

24 

C 

N 

(24) 

76 

L 

(76) 

128 

c 

L 

(128) 

180 

c 

(180) 

232 

b 

(232) 

25 

E 

M 

(25) 

77 

M 

(77) 

129 

I 

V 

(129) 

181 


(181) 

233 

0 

(233) 

26 

S 

B 

(26) 

78 

N 

(78) 

130 

B 

G 

(130) 

182 

ft 

(182) 

234 

6 

(234) 

27 

E 

c 

(27) 

79 

0 

(79) 

131 

I 

B 

(131) 

183 

ft 

(183) 

235 

& 

(235) 

28 

F s 

(28) 

80 

P 

(80) 

132 

U 

JL 

(132) 

184 

i 

(184) 

236 

§ 

(236) 

29 

G 

5 

(29) 

81 

Q 

(81) 

133 

I 

(133) 

185 

6 

(185) 

237 

0 

(237) 

30 

R 

5 

(30) 

82 

R 

(82) 

134 

B 

£ 

(134) 

186 

a 

(186) 

238 

Y 

(238) 

31 

U 

5 

(31) 

83 

S 

(83) 

135 

£ 

(135) 

187 

£ 

(187) 

239 

y 

(239) 

32 


(32) 

84 

T 

(84) 

136 

14 

H 

(136) 

188 

¥ 

(188) 

240 

1> 

(240) 

33 

1 

(33) 

85 

U 

(85) 

137 

R 

D 

(137) 

189 

§ 

(189) 

241 

P 

(241) 

34 

" 

(34) 

86 

V 

(86) 

138 

Y 

E 

(138) 

190 

/ 

(190) 

242 

F 

2 

(242) 

35 

# 

(35) 

87 

W 

(87) 

139 

G 

R 

(139) 

191 

c 

(191) 

243 

F 

3 

(243) 

36 

$ 

(36) 

88 

X 

(88) 

140 

C 

Y 

(140) 

192 

§ 

(192) 

244 

F 

a 

(244) 

37 

% 

(37) 

89 

Y 

(89) 

141 

B 

U 

(141) 

193 

§ 

(193) 

245 

i 

□ 

(245) 

38 

& 

(38) 

90 

Z 

(90) 

142 

M 

G 

(142) 

194 

6 

(194) 

246 

- 

(246) 

39 

i 

(39) 

91 

[ 

(91) 

143 

B 

K 

(143) 

195 

Q 

(195) 

247 

i 

(247) 

40 

( 

(40) 

92 

\ 

(92) 

144 

9 

0 

(144) 

196 

A 

(196) 

248 

i 

(248) 

41 

) 

(41) 

93 

] 

(93) 

145 

9 

1 

(145) 

197 

A 

(197) 

249 

3. 

(249) 

42 

* 

(42) 

94 

A 

(94) 

146 

9 

2 

(146) 

198 

6 

(198) 

250 

SL 

(250) 

43 

+ 

(43) 

95 


(95) 

147 

9 

3 

(147) 

199 

u 

(199) 

251 

« 

(251) 

44 

| 

(44) 

96 


(96) 

148 

9 

a 

(148) 

200 

A 

(200) 

252 

■ 

(252) 

45 


(45) 

97 

a 

(97) 

149 

9 

5 

(149) 

201 

£ 

(201) 

253 

» 

(253) 

46 

# 

(46) 

98 

b 

(98) 

150 

9 

6 

(150) 

202 

6 

(202) 

254 

+ 

(254) 

47 

/ 

(47) 

99 

c 

(99) 

151 

9 

7 

(151) 

203 

u 

(203) 

255 

a 

(255) 

48 

0 

(48) 

100 

d 

(100) 

152 

9 

9 

(152) 

204 

a 

(204) 




49 

1 

(49) 

101 

e 

(101) 

153 

9 

9 

(153) 

205 

e 

(205) 




50 

2 

(50) 

102 

f 

(102) 

154 

9 

A 

(154) 

206 

6 

(206) 




51 

3 

(51) 

103 

g 

(103) 

155 

9 

B 

(155) 

207 

a 

(207) 
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FRENCH Lexical Order 

The FRENCH lexical order table contains two special entries. The hyphen character (-) is 
assigned as a “don’t care” character and a “2 for 1” character replacement is made for the “6” 
character. 

(5 = ss 

A string containing the hyphen will match the same string without the hyphen and a string 
containing only a hyphen will match the null string. For example: 

LEXICAL ORDER IS FRENCH 

IF "RE-STORE"="RESTORE" THEN PRINT "TRUE" 

Prints: TRUE 

Case Conversions 

The following lists show the UPC$ and LWC$ transformations for the FRENCH lexical order. 

UPC$ 


abcdefghij klmnopqrstuvwxyz^naeouaeouaeoiiaeouiai 0 *iiBadosyt 

ABCDEFGHIJKLMNOPQRSTUVWX YZQnaeouaeouaeouaeou i a i0ifi iBfiDoSY* 

LWC$ 


ABCDEFGHIJKLMNOPQRSTUVWXYZaaeee iiuuQNA0(fA6uEOAADiiooosuYF 
abcdefghij k1mnopqrstuvwxyzaaeeeiiuu^naesaoueoaadiiooosuy► 
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LEXICAL ORDER IS FRENCH 


Seq, 

Chr 

Num. 

Seq. 

Chr 

Num. 

Seq. 

Chr 

Num. 

Seq. 

Chr 

Num. 

Seq. 

Chr. Num. 


_ 

(45) 

51 

4 

(52) 

81 

P 

(80) 

113 

1 

(108) 

153 

7 

(248) 

0 

N 

U 

(0) 

52 

5 

(53) 

82 

Q 

(81) 

114 

m 

(109) 

154 

4 

(249) 

1 

5 

H 

(1) 

53 

6 

(54) 

83 

R 

(82) 

115 

n 

(110) 

155 

4 

(250) 

2 

S 

(2) 

54 

7 

(55) 

84 

S 

(83) 

116 

n 

(183) 

156 

« 

(251) 

3 

E 

X 

(3) 

55 

8 

(56) 

85 

6 

(235) 

117 

o 

(111) 

157 

■ 

(252) 

4 

E 

T 

(4) 

56 

9 

(57) 

86 

T 

(84) 

117 

6 

(194) 

158 

» 

(253) 

5 

E 

0 

(5) 

57 

: 

(58) 

87 

U 

(85) 

117 

6 

(198) 

159 

+ 

(254) 

6 

fl 

K 

(6) 

58 


(59) 

87 

0 

(173) 

117 

6 

(202) 

160 

i 

(127) 

7 

0 

(7) 

59 

< 

(60) 

87 

0 

(174) 

117 

6 

(206) 

161 


(160) 

8 

B 

5 

(8) 

60 

* 

(61) 

87 

u 

(219) 

117 

0 

(214) 

162 

B 

(177) 

9 

H 

T 

(9) 

61 

> 

(62) 

87 

u 

(237) 

117 

5 

(234) 

163 

B 

2 

(178) 

10 

L 

F 

(10) 

62 

? 

(63) 

88 

V 

(86) 

118 

P 

(112) 

164 

F 

2 

(242) 

11 

V 

T 

(11) 

63 

0 

(64) 

89 

Vi 

(87) 

119 

q 

(113) 

165 

F 

3 

(243) 

12 


(12) 

64 

A 

(65) 

90 

X 

(88) 

120 

r 

(114) 

166 

F 

4 

(244) 

13 

C 

R 

(13) 

64 

A 

(161) 

91 

Y 

(89) 

121 

s 

(115) 

167 

I 

D 

(245) 

14 

5 

0 

(14) 

64 

A 

(162) 

91 

Y 

(238) 

121 

B 

(222) 

168 

C 

L 

(128) 

15 

5 

I 

(15) 

64 

A 

(208) 

92 

z 

(90) 

122 

§ 

(236) 

169 

I 

V 

(129) 

16 

D 

L 

(16) 

64 

A 

(211) 

93 

£ 

(240) 

123 

t 

(116) 

170 

B 

G 

(130) 

17 

°1 

(17) 

64 

A 

(216) 

94 

[ 

(91) 

124 

u 

(117) 

171 

I 

B 

(131) 

18 

% 

(18) 

64 

A 

(224) 

95 

\ 

(92) 

124 

Q 

(195) 

172 

U 

JL 

(132) 

19 


(19) 

64 

A 

(225) 

96 

] 

(93) 

124 

u 

(199) 

173 

I 

id 

(133) 

20 


(20) 

65 

B 

(66) 

97 


(94) 

124 

u 

(203) 

174 

B 

JG 

(134) 

21 

N 

K 

(21) 

66 

C 

(67) 

98 


(95) 

124 

u 

(207) 

175 

I 

£ 

(135) 

22 

5 

Y 

(22) 

66 

Q 

(180) 

99 

N 

(96) 

125 

V 

(118) 

176 

w 

H 

(136) 

23 

E 

B 

(23) 

67 

D 

(68) 

100 

a 

(97) 

126 

VJ 

(119) 

177 

R 

D 

(137) 

24 

C 

N 

(24) 

68 

D 

(227) 

100 

a 

(192) 

127 

X 

(120) 

178 

Y 

E 

(138) 

25 

E 

M 

(25) 

69 

E 

(69) 

100 

a 

(196) 

128 

y 

(121) 

179 

G 

R 

(139) 

26 

5 

B 

(26) 

69 

£ 

(163) 

100 

a 

(200) 

128 

y 

(239) 

180 

C 

Y 

(140) 

27 

E 

C 

(27) 

69 

£ 

(164) 

100 

a 

(204) 

129 

z 

(122) 

181 

B 

U 

(141) 

28 

F s 

(28) 

69 

E 

(165) 

100 

a 

(212) 

130 

p 

(241) 

182 

M 

G 

(142) 

29 

G 

5 

(29) 

69 

£ 

(220) 

100 

£ 

(215) 

131 

{ 

(123) 

183 

B 

K 

(143) 

30 

R 

5 

(30) 

70 

F 

(70) 

100 

a 

(226) 

132 

1 

(124) 

184 

9 

0 

(144) 

31 

U 

5 

(31) 

71 

G 

(71) 

101 

b 

(98) 

133 

> 

(125) 

185 

9 

1 

(145) 

32 


(32) 

72 

H 

(72) 

102 

c 

(99) 

134 

- 

(126) 

186 

9 

2 

(146) 

33 

• 

(33) 

73 

I 

(73) 

103 

9 

(181) 

135 

* 

(168) 

187 

9 

3 

(147) 

34 

ii 

(34) 

73 

± 

(166) 

104 

d 

(100) 

136 


(169) 

188 

9 

a 

(148) 

35 

# 

(35) 

73 

X 

(167) 

105 

d 

(228) 

137 


(170) 

189 

9 

5 

(149) 

36 

$ 

(36) 

73 

± 

(229) 

106 

e 

(101) 

138 


(171) 

190 

9 

6 

(150) 

37 

% 

(37) 

73 

± 

(230) 

106 

§ 

(193) 

139 


(172) 

191 

9 

7 

(151) 

38 

& 

(38) 

74 

J 

(74) 

106 

a 

(197) 

140 

£ 

(175) 

192 

9 

9 

(152) 

39 

' 

(39) 

75 

K 

(75) 

106 

a 

(201) 

141 


(176) 

193 

9 

9 

(153) 

40 

( 

(40) 

76 

L 

(76) 

106 

e 

(205) 

142 

• 

(179) 

194 

9 

A 

(154) 

41 

) 

(41) 

77 

M 

(77) 

107 

f 

(102) 

143 

i 

(184) 

195 

9 

B 

(155) 

42 

* 

(42) 

78 

N 

(78) 

108 

g 

(103) 

144 

<L 

(185) 

196 

9 

C 

(156) 

43 

+ 

(43) 

79 

fi 

(182) 

109 

h 

(104) 

145 

a 

(186) 

197 

9 

D 

(157) 

44 

j 

(44) 

80 

0 

(79) 

110 

i 

(105) 

146 

£ 

(187) 

198 

9 

E 

(158) 

45 


(46) 

80 

0 

(210) 

110 

1 

(209) 

147 

¥ 

(188) 

199 

9 

F 

(159) 

46 

/ 

(47) 

80 

6 

(218) 

110 

1 

(213) 

148 

§ 

(189) 

200 

H 

(255) 

47 

0 

(48) 

80 

(!) 

(223) 

110 

1 

(217) 

149 

/ 

(190) 




48 

1 

(49) 

80 

6 

(231) 

110 

l 

(221) 

150 

C 

(191) 




49 

2 

(50) 

80 

<b 

(232) 

111 

3 

(106) 

151 

- 

(246) 




50 

3 

(51) 

80 

5 

(233) 

112 

k 

(107) 

152 


(247) 
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SPANISH Lexical Order 

The SPANISH lexical order table contains five special entries. Four of these entries are “1 for 
2” character replacements. When the following character pairs are found in a string, a single 
sequence number is used to represent the pair. 


CH = 68 

cH = 103 

Ch = 68 

ch = 103 

LL = 78 

1L = 113 

LI = 78 

11 = 113 


The remaining special case is a “2 for 1” entry for the “B” character. 

B = ss 

Case Conversions 

The following lists show the UPC$ and LWC$ transformations for the SPANISH lexical order. 

UPC$ 


abodefghij k1mnopqrstuvwxyz^naeouaeouaeouaeouiai b* iiBadosyk 

ABCDEFGHIJKLMNOPQRSTUVWXYZCnAEOUAEOUAEOUaEouIA l0itlIB aDosy? 
LWC$ 

ABCDEFGHI JKLMNOPQRSTUVWXYZAAEEEi iuugNA0iEA6GEOAADiio66suv> 

abcdefghij k 1 mnopqrstuvwxyzaaeeei i uujnaesaoueoaadi i ooosuyk 
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LEXICAL ORDER IS SPANISH 


Seq. 

Chr 

Num. 

Seq. 

Chr. Num . 

Seq. 

Chr 

Num. 

Seq. 

Chr. Num, 

Seq. 

Chr. Num. 

0 

N 

U 

(0) 

52 

4 

(52) 

84 

P 

(80) 

116 

1 

(108) 

157 

i 

7 

(248) 

1 

5 

H 

(1) 

53 

5 

(53) 

85 

Q 

(81) 

118 

m 

(109) 

158 

3L 

(249) 

2 

S 

X 

(2) 

54 

6 

(54) 

86 

R 

(82) 

119 

n 

(110) 

159 

£ 

(250) 

3 

E 

(3) 

55 

7 

(55) 

87 

S 

(83) 

120 

Pi 

(183) 

160 

« 

(251) 

4 

E 

T 

(4) 

56 

8 

(56) 

88 

£ 

(235) 

121 

o 

(111) 

161 

■ 

(252) 

5 

E 

0 

(5) 

57 

9 

(57) 

89 

T 

(84) 

121 

6 

(194) 

162 

» 

(253) 

6 

A 

K 

(6) 

58 

: 

(58) 

90 

U 

(85) 

121 

6 

(198) 

163 

+ 

(254) 

7 

0 

(7) 

59 

y 

(59) 

90 

0 

(173) 

121 

6 

(202) 

164 

i 

(127) 

8 

B 

5 

(8) 

60 

< 

(60) 

90 

0 

(174) 

121 

6 

(206) 

165 


(160) 

9 

H 

T 

(9) 

61 

= 

(61) 

90 

u 

(219) 

121 

0 

(214) 

166 

B 

1 

(177) 

10 

L 

F 

(10) 

62 

> 

(62) 

90 

u 

(237) 

121 

5 

(234) 

167 

B 

2 

(178) 

11 

V 

T 

(11) 

63 

? 

(63) 

91 

V 

(86) 

122 

P 

(112) 

168 

F 

2 

(242) 

12 

f f 

(12) 

64 

@ 

(64) 

92 

W 

(87) 

123 

q 

(113) 

169 

F 

3 

(243) 

13 

C 

R 

(13) 

65 

A 

(65) 

93 

X 

(88) 

124 

r 

(114) 

170 

F 

a 

(244) 

14 

5 

0 

(14) 

65 

A 

(161) 

94 

Y 

(89) 

125 

s 

(115) 

171 

□ 

(245) 

15 

5 

T 

(15) 

65 

A 

(162) 

94 

Y 

(238) 

125 

0 

(222) 

172 

c 

L 

(128) 

16 

D 

L 

(16) 

65 

A 

(208) 

95 

Z 

(90) 

126 

§ 

(236) 

173 

I 

V 

(129) 

17 

°1 

(17) 

65 

A 

(211) 

96 

* 

(240) 

127 

t 

(116) 

174 

B 

G 

(130) 

18 


(18) 

65 

A 

(216) 

97 

[ 

(91) 

128 

u 

(117) 

175 

I 

B 

(131) 

19 


(19) 

65 

A 

(224) 

98 

\ 

(92) 

128 

a 

(195) 

176 

U 

i- 

(132) 

20 


(20) 

65 

A 

(225) 

99 

] 

(93) 

128 

u 

(199) 

177 

I 

II 

(133) 

21 

N 

K 

(21) 

66 

B 

(66) 

100 

A 

(94) 

128 

u 

(203) 

178 

B 

£ 

(134) 

22 

5 

V 

(22) 

67 

C 

(67) 

101 


(95) 

128 

u 

(207) 

179 

£ 

(135) 

23 

E 

B 

(23) 

67 

c 

(180) 

102 

\ 

(96) 

129 

V 

(118) 

180 

W 

H 

(136) 

24 

C 

N 

(24) 

69 

D 

(68) 

103 

a 

(97) 

130 

VJ 

(119) 

181 

R 

D 

(137) 

25 

E 

M 

(25) 

70 

D 

(227) 

103 

a 

(192) 

131 

X 

(120) 

182 

Y 

E 

(138) 

26 

5 

B 

(26) 

71 

E 

(69) 

103 

a 

(196) 

132 

y 

(121) 

183 

G 

R 

(139) 

27 

E 

C 

(27) 

71 

£ 

(163) 

103 

k 

(200) 

132 

y 

(239) 

184 

C 

Y 

(140) 

28 

F s 

(28) 

71 

£ 

(164) 

103 

a 

(204) 

133 

z 

(122) 

185 

B 

U 

(141) 

29 

G 

5 

(29) 

71 

E 

(165) 

103 

a 

(212) 

134 

h 

(241) 

186 

M 

G 

(142) 

30 

R 

5 

(30) 

71 

£ 

(220) 

103 

£ 

(215) 

135 

{ 

(123) 

187 

B 

K 

(143) 

31 

U 

5 

(31) 

72 

F 

(70) 

103 

a 

(226) 

136 

i 

(124) 

188 

9 

0 

(144) 

32 


(32) 

73 

G 

(71) 

104 

b 

(98) 

137 

> 

(125) 

189 

9 

(145) 

33 

1 

(33) 

74 

H 

(72) 

105 

c 

(99) 

138 

- 

(126) 

190 

9 

2 

(146) 

34 

ii 

(34) 

75 

I 

(73) 

105 


(181) 

139 

* 

(168) 

191 

9 

3 

(147) 

35 

# 

(35) 

75 

i 

(166) 

107 

d 

(100) 

140 

* 

(169) 

192 

9 

a 

(148) 

36 

$ 

(36) 

75 

X 

(167) 

108 

d 

(228) 

141 

** 

(170) 

193 

9 

5 

(149) 

37 

% 

(37) 

75 

± 

(229) 

109 

e 

(101) 

142 


(171) 

194 

9 

6 

(150) 

38 

& 

(38) 

75 

± 

(230) 

109 

§ 

(193) 

143 


(172) 

195 

9 

7 

(151) 

39 

i 

(39) 

76 

J 

(74) 

109 


(197) 

144 

€ 

(175) 

196 

9 

8 

(152) 

40 

( 

(40) 

77 

K 

(75) 

109 

£ 

(201) 

145 

— 

(176) 

197 

9 

9 

(153) 

41 

) 

(41) 

78 

L 

(76) 

109 

e 

(205) 

146 

• 

(179) 

198 

9 

A 

(154) 

42 

* 

(42) 

80 

M 

(77) 

110 

f 

(102) 

147 

i 

(184) 

199 

9 

B 

(155) 

43 

+ 

(43) 

81 

N 

(78) 

111 

g 

(103) 

148 

6 

(185) 

200 

9 

C 

(156) 

44 

J 

(44) 

82 

fl 

(182) 

112 

h 

(104) 

149 

a 

(186) 

201 

9 

D 

(157) 

45 

- 

(45) 

83 

0 

(79) 

113 

i 

(105) 

150 

£ 

(187) 

202 

9 

E 

(158) 

46 


(46) 

83 

0 

(210) 

113 

I 

(209) 

151 

¥ 

(188) 

203 

9 

F 

(159) 

47 

/ 

(47) 

83 

d 

(218) 

113 

1 

(213) 

152 

§ 

(189) 

204 

a 

(255) 

48 

0 

(48) 

83 

d 

(223) 

113 

1 

(217) 

153 

/ 

(190) 




49 

1 

(49) 

83 

6 

(231) 

113 

l 

(221) 

154 

C 

(191) 




50 

2 

(50) 

83 

6 

(232) 

114 

j 

(106) 

155 

- 

(246) 




51 

3 

(51) 

83 

5 

(233) 

115 

k 

(107) 

156 

i 

7 

(247) 
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SWEDISH Lexical Order 

The SWEDISH lexical order table includes one “2 for 1” character replacement entry. When 
the “8” character is found in a string, two sequence numbers are generated, as if two charac¬ 
ters were found in the string. 

8 = ss 

Case Conversions 

The following lists show the UPC$ and LWC$ transformations for the SWEDISH lexical order. 

UPC$ 

abcdefghij k1mnopqrstuvwxyz9riae6uae6uae6uaeouiai0*ilBadosyl* 

ABCDEFGHIJKLMNOPQRSTUVMXYZQnaeouaeouaeouaeou i a i 0f£i iBaDosy* 

LWC$ 

ABCDEFGHIJKLMNOPQRSTUVNX YZaaeee ii uuQna0^aoueoaaDi iooosuY* 
abcdefghijklmnopqrstuvwxyzaaeeeiiuu9na0*aoue6aadiiooosuy^ 





String Manipulation 155 


LEXICAL ORDER IS SWEDISH 


Seq. 

Chr 

. Hum, 

Seq. 

Chr 

Nura. 

Seq. 

Chr 

Nub. 

Seq. 

Chr 

Norn . 

Seq, 

Chr 

■. Nub. 

0 

N 

U 

(OJ 

52 

4 

(52) 

104 

± 

(229) 

154 

aE 

(215) 

206 

i 

(248) 

1 

5 

H 

(1) 

53 

5 

(53) 

105 

± 

(230) 

155 

a 

(212) 

207 

A 

(249) 

2 

5 

X 

(2) 

54 

6 

(54) 

106 

1 

(166) 

156 

k 

(196) 

208 

£ 

(250) 

3 

E 

X 

(3) 

55 

7 

(55) 

107 

X 

(167) 

157 

k 

(200) 

209 

« 

(251) 

4 

E 

T 

(4) 

56 

8 

(56) 

108 

S 

(182) 

158 

k 

(192) 

210 

■ 

(252) 

5 

E 

0 

(5) 

57 

9 

(57) 

109 

6 

(231) 

159 

a 

(204) 

211 

» 

(253) 

6 

ft 

K 

(6) 

58 

; 

(58) 

110 

<b 

(232) 

160 

a 

(226) 

212 

+ 

(254) 

7 

4 

(7) 

59 

) 

(59) 

111 

(!) 

(223) 

161 


(181) 

213 

i 

(127) 

8 

E 

5 

(8) 

60 

< 

(60) 

112 

6 

(218) 

162 

d 

(228) 

214 


(160) 

9 

H 

T 

(9) 

61 

s 

(61) 

113 

G 

(233) 

163 

£ 

(201) 

215 

B i 

(177) 

10 

L 

F 

(10) 

62 

> 

(62) 

114 

0 

(210) 

164 

§ 

(193) 

216 

B 

2 

(178) 

11 

V 

T 

(11) 

63 

? 

(63) 

115 

£ 

(235) 

165 

e 

(205) 

217 

F 

2 

(242) 

12 

f f 

(12) 

64 

@ 

(64) 

116 

u 

(237) 

166 

1 

(213) 

218 

F 

3 

(243) 

13 

C 

R 

(13) 

65 

A 

(65) 

117 

0 

(173) 

167 

1 

(217) 

219 

F 

a 

(244) 

14 

5 

0 

(14) 

66 

B 

(66) 

118 

0 

(174) 

168 

i 

(209) 

220 

0 

(245) 

15 

5 

I 

(15) 

67 

C 

(67) 

119 

0 

(219) 

169 

l 

(221) 

221 

c 

L 

(128) 

16 

D 

(16) 

68 

D 

(68) 

120 

Y 

(238) 

170 

Pi 

(183) 

222 

I 

V 

(129) 

17 


(17) 

69 

E 

(69) 

121 

£ 

(240) 

171 

6 

(198) 

223 

B 

G 

(130) 

18 


(18) 

70 

F 

(70) 

122 

[ 

(91) 

172 

6 

(202) 

224 

I 

B 

(131) 

19 


(19) 

71 

G 

(71) 

123 

\ 

(92) 

173 

6 

(194) 

225 

U 

i. 

(132) 

20 


(20) 

72 

H 

(72) 

124 

] 

(93) 

174 

6 

(206) 

226 

I 

y. 

(133) 

21 

N 

V- 

(21) 

73 

I 

(73) 

125 

A 

(94) 

175 

5 

(234) 

227 

B 

£ 

(134) 

22 

5 

(22) 

74 

J 

(74) 

126 


(95) 

176 

0 

(214) 

228 

I 

£ 

(135) 

23 

E 

B 

(23) 

75 

K 

(75) 

127 

\ 

(96) 

177 

§ 

(236) 

229 

w 

H 

(136) 

24 

C 

N 

(24) 

76 

L 

(76) 

128 

a 

(97) 

178 

u 

(199) 

230 

R 

D 

(137) 

25 

E 

M 

(25) 

77 

M 

(77) 

129 

b 

(98) 

179 

a 

(203) 

231 

Y 

E 

(138) 

26 

5 

B 

(26) 

78 

N 

(78) 

130 

c 

(99) 

180 

Q 

(195) 

232 

G 

R 

(139) 

27 

E 

c 

(27) 

79 

0 

(79) 

131 

d 

(100) 

181 

u 

(207) 

233 

C 

Y 

(140) 

28 


(28) 

80 

P 

(80) 

132 

e 

(101) 

182 

y 

(239) 

234 

B 

U 

(141) 

29 

6 

5 

(29) 

81 

Q 

(81) 

132 

4 

(197) 

183 

b 

(241) 

235 

M 

G 

(142) 

30 

R 

5 

(30) 

82 

R 

(82) 

133 

f 

(102) 

184 

{ 

(123) 

236 

B 

K 

(143) 

31 

U 

5 

(31) 

83 

S 

(83) 

134 

g 

(103) 

185 

i 

(124) 

237 

9 

0 

(144) 

32 


(32) 

84 

T 

(84) 

135 

h 

(104) 

186 

> 

(125) 

238 

9 

1 

(145) 

33 

• 

(33) 

85 

U 

(85) 

136 

i 

(105) 

187 

- 

(126) 

239 

9 

2 

(146) 

34 

" 

(34) 

86 

V 

(86) 

137 

j 

(106) 

188 

* 

(168) 

240 

9 

3 

(147) 

35 

# 

(35) 

87 

W 

(87) 

138 

k 

(107) 

189 


(169) 

241 

9 

a 

(148) 

36 

$ 

(36) 

88 

X 

(88) 

139 

1 

(108) 

190 


(170) 

242 

9 

5 

(149) 

37 

% 

(37) 

89 

Y 

(89) 

140 

ro 

(109) 

191 

*■ 

(171) 

243 

9 

6 

(150) 

38 

& 

(38) 

90 

Z 

(90) 

141 

n 

(110) 

192 


(172) 

244 

9 

7 

(151) 

39 

i 

(39) 

91 

A 

(211) 

142 

o 

(111) 

193 

£ 

(175) 

245 

9 

8 

(152) 

40 

( 

(40) 

92 

A 

(208) 

143 

P 

(112) 

194 

~ 

(176) 

246 

9 

9 

(153) 

41 

) 

(41) 

93 

A 

(224) 

144 

q 

(113) 

195 


(179) 

247 

9 

A 

(154) 

42 

* 

(42) 

94 

A 

(161) 

145 

r 

(114) 

196 

i 

(184) 

248 

9 

B 

(155) 

43 

+ 

(43) 

95 

A 

(162) 

146 

s 

(115) 

197 

<L 

(185) 

249 

9 

C 

(156) 

44 

; 

(44) 

96 

A 

(216) 

146 

3 

(222) 

198 

0 

(186) 

250 

9 

D 

(157) 

45 


(45) 

97 

A 

(225) 

147 

t 

(116) 

199 

£ 

(187) 

251 

9 

E 

(158) 

46 

9 

(46) 

98 

C 

(180) 

148 

u 

(117) 

200 

V 

(188) 

252 

9 

F 

(159) 

47 

/ 

(47) 

99 

D 

(227) 

149 

V 

(118) 

201 

§ 

(189) 

253 

a 

(255) 

48 

0 

(48) 

100 

£ 

(220) 

150 

Vf 

(119) 

202 

/ 

(190) 




49 

l 

(49) 

101 

£ 

(163) 

151 

X 

(120) 

203 

C 

(191) 




50 

2 

(50) 

102 

£ 

(164) 

152 

Y 

(121) 

204 

- 

(246) 




51 

3 

(51) 

103 

£ 

(165) 

153 

z 

(122) 

205 


(247) 
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User-defined LEXICAL ORDER 

The following program will generate the worksheet on the next page. The worksheet is handy 
when creating a user-defined lexical order. 


10 DIM Lb*C 1 ] ,F1$C23] tF2*C233,F3*[14] ,F4$[201 ,Fa 11 1 C961 ,F1p$[22] ,F2 p$[22] 

20 INTEGER I 

30 OUTPUT PRTi"LEXICAL ORDER TABLE WORKSHEET !seq-num;mode-type.mode-entr 

y ! " 

40 OUTPUT PRT 

50 L b $ = " » " 

GO FIp$=" tDD iX ! : . !i'. 

70 F1 $ =" tDDD iXi""! : . ! ! 

80 F 2 p $ = " ,X ,A ,X : : . ! !. 

90 F2$ = " .XX .A .X ! : . ! !. 

100 F4$ =" .DD »X . " "! : !! 

110 F3$ =" .""Mode LenSth' 

120 Falt$ = Flp$&F2$&Fl$S:F2t 
130 FOR 1=0 TO G3 
140 SELECT I 

150 CASE 0 

ISO OUTPUT PRT USING Lb$&Fa 1 t$8.F3* i I .CHR* ( I+G4 ) . I +128 .CHR$ ( I + 192 ) 

170 CASE <32 

180 OUTPUT PRT USING Lb$&Falt$&:F4$iI ,CHR$(I+G4) .1 + 128.CHR$(1 + 192) .1-1 

190 CASE ELSE 

200 OUTPUT PRT USING Lb*fcF2p*8.RPT*(F2$ .3)&F4$!CHR$(I) ,CHR$( I+G4 ) ,CHR$(I +12 

8) »CHR$(1 + 192) ,1-1 

210 END SELECT 

220 OUTPUT PRT 

230 NEXT I 

240 END 
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LEXICAL ORDER TABLE WORKSHEET |seq-num:mode-type.mode-entr y | 


0 

1 

2 

3 

4 

5 

6 
7 
3 
9 

10 
11 
12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 


0 

A 

B 

C 

D 

E 

F 

G 

H 

I 

J 

K 

L 

M 

N 

0 

P 

Q 

R 

S 

T 

U 

V 

w 

X 

Y 

z 

c 

\ 

] 


128 

129 

130 

131 

132 

133 

134 

135 

136 

137 

138 

139 

140 

141 

142 

143 

144 

145 

146 

147 

148 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 


! 

H 

# 

$ 

m / m 

& 

/ 

< 

> 

* 

+ 


3 

1 

2 

3 

4 

5 

6 
7 
3 
9 


< 

> 

? 


a 

b 

c 

d 

e 

f 

g 

h 

1 

•j 

k 

1 

m 

n 

o 

P 

q 

r 

s 

t 

u 

u 

w 

X 

y 

2 

< 

I 

> 

*v 

£ 


A 

± 

6 

0 

A 

i 

6 



a 

e 

6 

u 

a 

e 

6 

u 

a 

e 

6 

u 

a 

e 

6 

u 

A 

l 

0 

E 

a 

i 

0 

% 

A 

l 

0 

U 

t 

¥ 

13 


M o d e 
0 
1 
2 

3 

4 

5 

6 

7 

8 
9 

10 
1 1 
12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 


L e n g t h 
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User-Defined Lexical Orders 

A lexical order can be created for applications that require special collating sequences. If you 
can use one of the predefined lexical orders, you may wish to only skim this section. 

A program called LEX-AID has been supplied (on the BASIC Utilities Library disc) to simplify the 
creation of user-defined lexical orders. Before running the program it will be neccessary to have an 
understanding of the terms used in this section. Using the LEX-AID program is described in the 
BASIC Utilities Library manual. 

Basically, a 321 element (0 thru 320) INTEGER array is dimensioned, filled with sequence 
numbers and mode entries, and the new lexical order is established by the following statement. 

LEXICAL ORDER IS Tablet*) 

Where Table ( * ) is any valid INTEGER array name. 

The following illustration shows the general construction of a user-defined lexical table created 
in an INTEGER array. 


COLLATING 

SECTION 


255 

256 

257 


320 


# OF MODE ENTRIES 


MODE TABLE 
SECTION 


The first 256 elements (0 through 255) contain the sequence number to be used in place of the 
character’s ASCII value. For special characters, a mode type and mode table pointer are also 
stored in these elements. 

The next element (256) contains the number of entries in the mode table. This value can range 
from 0 (no mode table) thru 64 (a full mode table). 

The remaining 64 elements (257 thru 320) contain the optional mode table entries assigned to 
special characters. 
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Sequence Numbers 

Normally, comparing two strings results in the computer comparing the ASCII values of the 
characters. When the computer makes the string comparison “A”<“B”, the ASCII value of 
“A” (65) is compared to the ASCII value of the letter “B” (66) resulting in the 
comparison: 65<66, which is true. 

Now suppose that a new value (sequence number) could be assigned to each of the ASCII 
characters. We might wish to assign the letter “A” a sequence number greater than the sequ¬ 
ence number assigned to the letter “B”. If such an assignment were made, the comparison 
“A”<“B”, would now be false. 

Once a lexical order is invoked, if two strings are compared, the strings are first converted into 
two series of sequence numbers and the comparison is then based on the sequence numbers. 

The LEXICAL ORDER IS statement’s primary purpose is to assign a sequence number to each 
character. However, this is not always enough to handle certain character combinations and 
special cases encountered in other languages. Special characters have a mode entry included 
with the sequence number. 

Mode Entries 

Each of the first 256 array elements (0 thru 255) contains the sequence number to be used in 
place of the character’s ASCII value. Optionally, a mode entry can be included. 

Internally, an integer array element uses two bytes (16 bits) of memory. In the following 
diagram, the array element is divided into its upper, and lower bytes. The upper byte contains 
the sequence number and the lower byte is used if the character has a mode entry. 


array element 


upper byte 


lower byte 


sequence number 


optional mode entry 


The lower byte is further divided into two parts. The upper-most 2-bits are used to represent 
one of the four mode types. The remaining 6-bits store an index (pointer) to the actual mode 
table entries. This method allows all the necessary information, for each character, to be stored 
as a single element in the INTEGER array. 


lower byte 


mode type 


mode table index 


Mode Type 

Any one of the following mode types can be assigned to a character. 

• Don’t Care Characters (Mode type: 0) 

• “1 for 2” Character Replacements (Mode type: 1) 

• “2 for 1” Character Replacements (Mode type: 2) 

• Accent Priority (Mode type: 3) 
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Mode Index 

The mode index points to the actual mode table entry associated with the particular character. 
Up to 64 indexes are allowed (0 thru 63); however, some mode types use more than one table 
entry. 

Bits, Bytes, and Mode Types 

Each INTEGER array element stores a signed-integer in the range: —32768 thru 32767. 
Internally, the number is stored as a 16-bit 2’s complement value. 

Bits are usually numbered in descending order and include bit 0, so 16 bits are numbered as 
follows. 


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

_ 16-bit 2’s complement value 


However, we want to store one of 256 possible sequence numbers and optionally, a mode type 
and mode table index. Since there are 256 characters used with the LEXICAL ORDER IS 
statement, and 8 bits are needed to store one of 256 possible values (2^8 = 256), it is 
convenient to think of the bits arranged as two bytes (a byte contains 8 bits). 


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 


upper byte 


lower byte 


The upper byte is used to hold the sequence number and the lower byte contains the mode 
entry information. The algorithm below will produce a signed 16-bit integer from two unsigned 
8-bit bytes. 

Integer = (25G*Upper + Lower) - (Upper>127)*G553G 

The process can be reversed. 

IF InteSeKO THEN I n t e 3 e r= I n t e 3e r + G5536 
Upper=Inte3er DIP 256 
Lower=Inte£fer MOD 25G 

The lower byte is further divided into two groups. Two bits hold one of four mode types 
(2~2 = 4) and the remaining six bits are for one of 64 mode indexes (2~6 = 64). 


7 6 5 4 3 2 1 0 


sequence number 


type 


index 


A “1 for 2” entry is signified by bit-6 being set. Therefore the value of the lower byte can range 
from 64 thru 126. (a “1 for 2” requires at least 2 entries.) 

A “2 for 1” entry has bit-7 set. The value of the lower byte can range from 128 thru 191. 

An “Accent priority” entry has both bit-6 and bit-7 set. The value of the lower byte ranges from 
192 thru 255. 
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’’Don’t Care” Characters 

A character can be removed from the collation sequence. To mark a character as a “don’t 
care”, the mode type is 0 (the same as a regular character) but the mode table index is set to 1. 


sequence number 


type 


index 


any value 


0 


1 


The mode index need not point to a valid table entry, but must be a “1” to indicate a “don’t 
care” character. 

For example, the FRENCH lexical table lists the hyphen (-) as a “don’t care” character. Thus, 
the hyphen is ignored when a string comparison is being made. The entry appears: 


(45) 


sequence number 


type 


index 


45 


0 


1 


You may wish to include “don’t care” characters in your own lexical tables. A string containing 
only “don’t care” characters will match the null string. 


The following short program illustrates the operation 


of a “don’t care” character. 


10 

Return**"RESTORE" 




20 

A3ain$="RE-STORE" 




30 

! 




40 

LEXICAL ORDER IS ASCII 




50 

IF Restore$=A3ain$ THEN 

PR 

INT 

“True 

GO 

LEXICAL ORDER IS FRENCH 




70 

IF Restore$=A3ain$ THEN 

PR 

INT 

"True 

80 

END 





for ASCII" 
for FRENCH" 


Results: 

True for FRENCH 


“1 for 2” Character Replacement 

This type of mode table entry indicates that one sequence number is to be used for two 
consecutive characters. It should be remembered that no characters are actually replaced by 
this operation, only that a single sequence number is to be used when the two characters are 
found adjacent to each other. 

The following entry is placed in the collating section of the lexical table. 


sequence number 


normal sequence number 


type 


mode index 


index 
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If a character marked as a “1 for 2” is found in a string, the next character is accessed and 
compared to the list of possible secondary characters in the mode table section. 


(257 + index) 


number of entries to check 

second character 

sequence number for this pair 

second character 

sequence number for this pair 


If the character does not match any of the secondary characters in the mode table, the original 
character’s sequence number is used and processing continues. If a match is found, the sequ¬ 
ence number for the pair is used and processing continues with the character following the 
secondary character. 

For example, the SPANISH collating sequence has a “1 for 2” replacement for the letters 
“CH” or “Ch”. The letter “C” is marked as a “1 for 2” character. When the letter is encoun¬ 
tered in a string, the next character is accessed and compared to the list of possible secondary 
characters (uppercase H and lowercase h). The appropriate sequence number is then used for 
the pair. If the character following the letter “C” is not found in the list of possible secondary 
characters, the sequence number for “C” is used and processing continues with the next 
character. 

You can override a “1 for 2” character replacement by inserting a “Don’t Care” character 
between the two characters that would otherwise be replaced by a single sequence number. 

The SPANISH table entry for the character sequence “CH” is below. In the collating section, 
the first letter of the sequence has the following entry: 


sequence number _type_ mode index 


67 (C) 

1 

1 

69 (D) 

0 

0 


(257 + 1) 
(257 + 2) 
(257 + 3) 


number of entries to check (2) 

second character (H) 

sequence number for pair (68) 

second character (h) 

sequence number for pair (68) 


The sequence number assigned to the two-character combination is greater than the sequence 
number for the letter “C” and less than the sequence number for the letter “D”. Therefore, a 
word beginning with the characters “CH” will collate after all words starting with the letter “C” 
followed by any other character. 
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The following program shows the sorting order for the letters “CH” in the SPANISH lexical 
order. 


5 DIM A$(3)[3] 

10 A$( 1 ) = "CGA" 

20 A$(2)="CHA" 

30 A$ (3) = " CIA" 

40 LEXICAL ORDER IS 
50 MAT SORT A$(*) 

GO PRINT A$ ( *) 

70 END 

Produces: 


SPANISH 


CGA CIA CHA 


It should be noted that a character may have more than one secondary character combination. 
This is demonstrated by having both upper and lower case entries. Other secondary characters 
could have been included in the same manner. The first mode table entry contains the number 
of secondary characters to check and must be in the range: 0 thru 63. 

“2 for 1” Character Replacement 

When a “2 for 1” mode entry is specified, it indicates that the character should be represented 
by two sequence numbers (as if there were two characters in the string). The first sequence 
number is stored with the character as usual. The mode index points to the mode table entry 
that contains the second sequence number to be used for that character. 


sequence number 


type 


mode index 


1st sequence number 


index 


The mode table entry actually contains two sequence numbers. If the original character was 
upper case, the next character in the string will determine whether the upper or the lower 
sequence number is used. If the original character was a lower case letter, the lower sequence 
number is always used. 


(257 + index) 


2nd sequence number (UPC) 


2nd sequence number (LWC) 


Several “2 for 1” characters are in the GERMAN lexical order. For instance, the character “A” 
is equivalent to “AE” and has the following entry in the collating section. 



sequence number 

type 

mode index 

(216) 

65 (A) 

2 

index 
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The index points to the following entry in the mode table. 


(257 -(- index) 


upper 


lower 


75 (E) 


124 (e) 


In some cases, such as the character “13”, both upper and lower bytes contain the sequence 
number for the same character(s). This results in the same sequence numbers being generated 
regardless of the case of the next character. 

Accent Priority 

Accent Priority can be used as the final arbitrator of string comparisons. If you examine the 
lexical tables you will often find the same sequence number assigned to more than one charac¬ 
ter. Therefore, it is possible for two different strings to produce identical series of sequence 
numbers. The two strings will be considered equal unless at least one character, in each string, 
has been assigned different accent priorities. 

Accent priority is established by assigning a value, in the range: 0 thru 63, to the character. Any 
character not already assigned a mode type may be assigned a priority. A priority of zero is 
assumed for all characters that haven’t been assigned a priority. 


sequence number 


type 


mode index 


normal sequence number 


priority 


In the FRENCH lexical order, the characters: A, A, and A have been assigned the same 
sequence number (64). Assume the characters were assigned the following priorities. 

Character Priority 

A 0 (default priority) 

A 1 

A 2 


The characters can now be distinguished from one another and will collate in the following 
order. 

A < A < A 

When two strings are compared, each string is first converted into a series of sequence num¬ 
bers. The comparison is then determined (in most cases) by the greater sequence numbers or 
the longer series of sequence numbers. 

In the event both strings produce identical series of sequence numbers, the series of priorities 
are checked. The string containing the characters with the higher priority is the greater string. 
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User-Defined Functions 
and Subprograms 


Chapter 

6 


Introduction 

One of the most powerful constructs available in any language is the subprogram (a user- 
defined function is a special form of subprogram). A subprogram can do everything a main 
program can do except that it must be invoked or “called” before it is executed, whereas a 
main program is executed by pressing the RUN key. In a sense, pressing the RUN key is how 
you “call” a main program. 

A subprogram has its own “context” or state as distinct from a main program and all other 
subprograms. This means that every subprogram has its own set of variables, its own softkey 
definitions, its own DATA blocks, and its own line labels. There are several benefits to be 
realized by taking advantage of subprograms: 

• The subprogram allows the programmer to take advantage of the “Top-Down” method of 
designing programs. In this technique, the problem to be solved is broken up into a set of 
smaller and more easily solvable problems. These smaller problems can in turn be broken 
up into smaller problems yet, and so on. This technique has been shown to greatly improve 
the design, coding, and testing of programs, and will be discussed further at the end of the 
chapter. 

• By separating all the details of performing the subtasks from the overall logic flow of the 
main program, the program is much easier to read from the subprogram calls. The pro¬ 
grammer can see at a high level what he’s trying to accomplish, rather than immediately 
getting lost in the details of each little sub-task. 

• One of the most time-consuming parts of writing a program is debugging it, or forcing it to 
run correctly. The time consuming part of fixing bugs in a program is finding where the bug 
is in the first place. By using subprograms and testing each one independently of the 
others, it is easier to locate problems, and hence to fix them. 

• Often, a programmer may want to perform the same task from several different areas of his 
program. For example, a set of readings may need to be taken from a voltmeter after each 
of four different input signals are fed through a circuit being tested. The same subprogram 
may be used to set up the voltmeter and take the readings, while different pieces of code 
would have to be used to set up the differing input conditions. Thus, subprograms can be 
used to economize on the overall size of the program. 

• Finally, libraries of commonly used subprograms can be assembled for widespread use. 
Many different users doing diverse types of problems still may require some identical 
subprograms. For instance, an engineer may be using a subprogram to plot an array of data 
that he gathered from a spectrum analyzer, while the marketing person down the hall may 
be using the same subprogram to plot an array of data representing next year’s sales 
forecast. 
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Some Startup Details 

Location 

A subprogram is located after the body of the main program, following the main program’s 
END statement. (The END statement must be the last statement in the main program except for 
comments.) Subprograms may not be nested with other subprograms, but are physically delim¬ 
ited from each other with their heading statements (SUB or DEF) and ending statements 
(SUBEND or FNEND). 

Naming 

A subprogram has a name which may be up to fifteen characters long, just as with line labels 
and variable names. Here are some legal subprogram names: 

Initialize 
Read_dvm 
Sort_2_d_array 
Plot_data 
(Katakana name) 

Because up to 15 characters are allowed for naming subprograms, it is easy and convenient to 
name subprograms in such a way as to reflect the purpose for which the subprogram was 
written. 

For Example 

The following example shows a program which uses subprograms. 


10 OPTION BASE 1 
20 DIM N u m b e r s ( 2 0 ) 

30 CALL Bui1d_array(Numbers(* ) 1 20) 

40 CALL Sort.array(Numbers(*) *20) 

50 PRINT FNSum_array(Numbers(#)>20) 

B0 END 

70 SUB Build-array(X(*) »N) 

80 ! )<(*) is the array to be defined 

90 ! N tells how many elements are in the array 

100 ! (1 is assumed to be the lower index) 

110 FOR 1=1 TO N 

120 DISP "ELEMENT #"? I 5 

130 INPUT "?" »X< I ) 

140 NEXT I 
150 SUBEND 

ISO SUB So rt.array(A(*) > N) 

170 ! A(*) is array to be sorted 

180 ! N tells how many elements are in the array (1 is assumed 

190 ! to be the lower bound) 

200 ! Sort the array (elements 1-N) in increasing order 

210 ! Algorithm used: Shell sort or Diminishing increment sort 

220 ! Ref: Knuth * Donald E ♦> The Art of Computer Programming 

230 ! 0o1♦ 3 (Sorting and Searching) ♦ (Addison-Wes1ey 1973) 

240 ! pp. 84-85 

250 INTEGER T »S*H»I tJ 

260 REAL Temp 

270 T=INT(L0G(N)/L0G(2)) ! # of diminshinS increments 

280 FOR S = T TO 1 STEP -1 

290 H = 2 A (S- 1 ) ! ♦.* IS»8»4#2»1 

300 FOR J=H+1 TO N 
310 I= J-H 

320 T e m p = A(J) 

330 Decide: IF Temp>=A(I) THEN Insert 
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340 

350 

3B0 

370 

380 


Switch: A(I+H)= A(I ) 


Insert: A(I+H)=Temp 
NEXT J 


I = I - H 

IF I>=1 THEN Decide 


390 NEXT S 
400 SUBEND 

410 DEF FNSum.array(A<*> »N> 

420 ! Add A ( 1 ) ♦ ♦ ♦ A ( N ) 

430 INTEGER I 

440 REAL Array-total 

450 FOR 1=1 TO N 

480 Array_total=Array_total+A(I) 

470 NEXT I 

480 RETURN Array-total 
490 FNEND 

Lines 10 through 60 are the main program. As you can see, it does nothing but call subpro¬ 
grams, which in turn do all the work. Line 70 is the header for the subprogram which asks the 
user to enter the values stored in his array. Notice that the main program has declared the 
array’s name to be Numbers!*), but the subprogram uses the name X(*) to deal with the same 
array. The subprogram can name its variables whatever it wants without interfering with vari¬ 
ables used outside the subprogram’s context. The only variables that can be affected outside 
the subprogram’s context are those passed through the parameter list (as shown here) or 
through COM (discussed later). In both cases, the matching between the subprogram and the 
outside world is done through the position of the variable(s) in the parameter list or COM block, 
not the actual name of the variable(s). 

Starting at line 160 is the next subprogram which sorts the array into ascending order. The 
comments at the front of the subprogram serve to discuss the definition of the parameters used, 
and what effect the subprogram has on them. Also, the algorithm used is given, along with the 
proper reference material. It is an excellent idea to give a list of such pertinent details at the front 
of all subprograms. This makes debugging, modifying, optimizing, and re-using the subprogram 
much easier. 

Starting at line 410 we see an example of a function subprogram. Functions are similar to SUB 
subprograms in concept. This particular example just adds the elements of the array together 
and returns the final value to the main program, which prints it. 

The Difference Between a Function and a Subprogram 

A SUB subprogram (as opposed to a function subprogram) is invoked explicitly using the CALL 
statement. A function subprogram is called implicitly by using the function name in an expres¬ 
sion. It can be used in a numeric or string expression the same way a constant would be used, or 
it can be invoked from the keyboard. A function’s purpose is to return a single value (either a 
real number or a string). 

There are several functions that are built into the BASIC language which can be used to return 
values, such as SIN, SQR, EXP, etc. 

Y = SIN ( X ) +Ph as e 

Root 1 = (-B+SQR(B*B-4*A*C))/(2*A) 
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Communication 

As mentioned earlier, there are two ways for a subprogram to communicate with the main 
program or with other subprograms: parameter lists, and COM (blank and labeled). 

Parameter Lists 

The formal parameter list is part of the subprogram’s definition, just like the subprogram’s 
name. The formal parameter list tells how many values may be passed to a subprogram, the 
types of those values (string, INTEGER, REAL, array, I/O path name), and the names the 
subprogram will use to refer to those values. The subprogram has the power to demand that the 
calling context match the types declared in the formal parameter list exactly — otherwise an 
error results. The calling context provides a pass parameter list which corresponds with the 
formal parameter list provided by the subprogram. The pass parameter list provides the values 
for those inputs required by the subprogram, and also provides the storage for the output 
values. It is perfectly legal for both the formal and pass parameter lists to be null, or nonexistent. 

Here is a sample formal parameter list showing which types each parameter demands: 

SUB R e a d _ dum(@ D vm »A(*) > IN T E G E R Lowsr»Upper»Status$*ErrflaS) 

is an I/O path name which may refer to either an I/O device or a mass storage file. Its 
name here implies that it is a voltmeter, but it is perfectly legal to redirect I/O to a file just 
by using a different ASSIGN with @Dvm. 

A ( * ) is a REAL array. Its size is declared by the calling context. Without MAT, there is no way to 
find the size of the array except through information supplied explicitly by the calling 
context; hence the parameters Lower and Upper. 

Lower and Upper are declared here to be INTEGERS. Thus, when the calling program 
invokes this subprogram, it must supply either INTEGER variables or INTEGER ex¬ 
pressions, or an error will occur. 

Status* is a simple string which presumably could be used to return the status of the 
voltmeter to the main program. The length of the string is defined by the calling context. 

ErrflaSisa REAL number. The declaration of the string Status$ has limited the scope of the 
INTEGER keyword which caused Lower and Upper to require INTEGER pass parame¬ 
ters. 

There are two ways for the calling context to send values to a subprogram — pass by value, and 
pass by reference. Using pass by value, the calling context supplies a value and nothing more. 
Using pass by reference, the calling context actually gives the subprogram access to the calling 
context’s value area. The distinction is that a subprogram can not alter the value of data in the 
calling context if the data is passed by value, while the subprogram can alter the value of data in 
the calling context if the data is passed by reference. 
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The subprogram has no control over whether its parameters are sent using pass by value or 
pass by reference. That is determined by the calling context’s pass parameter list. In order for a 
parameter to be passed by reference, the pass parameter list (in the calling context) must use a 
variable for that parameter. In order for a parameter to be passed by value, the pass parameter 
list must use an expression for that parameter. Note that enclosing a variable in parentheses is 
sufficient to create an expression. Using pass by value, it is possible to pass an integer expres¬ 
sion to a REAL formal parameter (the INTEGER is converted to its REAL representation) 
without causing a type mismatch error. Likewise, it is possible to pass a REAL expression to an 
INTEGER formal parameter (the value of the expression is rounded to the nearest INTEGER) 
without causing a type mismatch error (an integer overflow error is generated if the expression 
is out of range for an INTEGER). Let’s look at our previous example from the calling side: 

CALL Rea d_duw(@ Volt meter»ReadiriSs(*) > 1 t 4 0 0 > S t a t u s $ > E r r f 1 a 3 ) 

@Uo It meter is the pass parameter which matches the formal parameter @Dvm in the 
subprogram. I/O path names are always passed by reference, which means the subpro¬ 
gram can close the I/O path or assign it to a different file or device. 

Read in 3s ( * ) matches the array A ( * ) in the subprogram’s formal parameter list. Arrays 
too, are always passed by reference. 

1, 400 are the values passed to the formal parameters Lower and Upper. Since constants are 
classified as expressions rather than variables, these parameters have been passed by 
value. Thus, if the subprogram used either Lower or Upper on the left hand side of an 
assignment operator, no change would take place in the calling context’s value area. 

S t a t u s $ is passed by reference here. If it were enclosed in parentheses, it would be passed by 
value. Notice that if it were passed by value, it would be totally useless as a method for 
returning the status of the voltmeter to the calling context. 

ErrflaSis passed by reference. 

OPTIONAL Parameters 

Another important feature of formal parameter lists is the OPTIONAL keyword. Any formal 
parameter list (the one defining the subprogram) may contain the keyword OPTIONAL some¬ 
where, although it isn’t required to. The OPTIONAL keyword indicates that any parameters 
that follow it are not required in the pass parameter list of a calling context — they are optional. 
On the other hand, all parameters preceding the OPTIONAL keyword are required. If no 
OPTIONAL appears in the subprogram’s parameter list, then all the parameters must be speci¬ 
fied, or an error will be generated. The rules requiring matching of parameter types apply to 
OPTIONAL parameters as well as to ordinary parameters. There is a standard function called 
NPAR which can be used inside the subprogram to find out how many pass parameters the 
calling context actually did use. (NPAR will return 0 if used inside the main program, or if no 
parameters were passed to a subprogram.) 

The OPTIONAL/NPAR combination is very effectively used in situations requiring external 
instrument setups. Most instruments have several different ranges, modes, settings, etc., which 
can be used depending upon the requirements of the user. Often, the user doesn’t require the 
entire flexibility the instrument has to offer, and would rather use some reasonable defaults. 
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Consider the HP 3437A Digital Voltmeter. Among other things, this device has two data 
formats (packed and ASCII), three trigger modes (internal, external, and hold/manual), three 
voltage ranges (0.1V, IV, and 10V), and also has programmable values for delay between 
readings, and numbers of readings taken. Naturally, the values used for the various settings will 
depend entirely upon the application for which the voltmeter is being used, but let’s make some 
assumptions: 

• The values for delay and number of readings are going to be changed frequently, so they 
will not be OPTIONAL parameters. 

• Of the remaining OPTIONAL parameters, the range is most likely to be altered. 

A reasonable setup routine for the voltmeter might look like this: 

2010 SUB Setup-dvm(@Dvm * INTEGER Re adin$stREAL De1 ay*0PTIONAL INTEGER PrandetPtr 
i^er * P f o r m a t) 

2020 SELECT NPAR 
2030 CASE 3 

2040 Fo rmat = 1 ! Default ASCII format 

2050 TriSSer=l ! Default internal triSsfer 

2 0 G 0 R a n 3 e = 2 ! Default 1 volt range 

2070 CASE 4 

2080 Format=l 

2090 T r i $ s e r = 1 

2100 Ranae=Pran$e 

2110 CASE 5 

2120 Fo rma t = 1 

2130 TriSSer=Ptris$er 

2140 Ran$e=Pran$e 

2150 CASE G 

2160 F o r m a t = P f o r m a t 

2170 TriSSer=PtrisSer 

2180 Ran$e=PranSe 

2100 END SELECT 

2200 OUTPUT 0Dvm5"N"5UAL$(Re adin*s) 5"SD" !0AL$(Delay) 5"SR"5VAL$(Rantfe) 5"T"?UAL$< 
Tri^er) 5 "F " 5 UAL$ (Format) 

2210 SUBEND 


Legal invocations of the Setup_dvm subprogram are: 


570 Setup_dvm(@Dvm t 100 * ♦001) 

630 Se t up_d vm(@D vm»500 t ♦05 »3) 

850 Setup_dvm(@D vm t 50 t ♦005 * 1 *2) 

1010 Set up_dvm(@Dvm 1 70 * ♦075 1 2#1 *2) 


Default Ransfe t T ri ^e r ^Format 
Default T ri55er tFormat 
Default Format 

Explicitly declare all values 


Notice in the example above that local variables are used instead of the formal parameters. This 
is because it is illegal to use an OPTIONAL parameter variable if that variable was not passed 
from the calling context. 

Other applications of the OPTIONAL/NPAR feature are limited only by the imagination, but 
here are a few ideas: 

Write a subprogram which sorts an array in ascending order unless an OPTIONAL parameter 
tells it to sort in descending order. 

Write a rootfinder routine which has an acceptance tolerance of ± 10 -6 unless overridden with 
an OPTIONAL parameter. 
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Write a program which keeps track of departmental expenses, including the account billed, the 
item or service purchased, the person incurring the expense, and optionally, the person author¬ 
izing the expense. 

COM Blocks 

Since we’ve discussed parameter lists in detail, let’s turn now to the other method a subpro¬ 
gram has of communicating with the main program or with other subprograms, the COM block. 

There are two types of COM (or common) blocks, blank and labeled. Blank COM is simply a 
special case of labeled COM (it is the COM whose name is nothing) with the exception that 
blank COM must be declared in the main program, while labeled COM blocks don’t have to be 
declared in the main program. Both types of COM blocks simply declare blocks of data which 
are accessible to any context having matching COM declarations. 

A blank COM block might look like this: 

10 OPTION BASE 1 

20 COM Conditions(15) t INTEGER tCmin >Cmax >iNuc1e a r_p i 1e * 

Pi 1e_status$[20] > T o 1 e ranee 

A labeled COM might look like this: 

30 COM /0 a 1 v e/ M ain(10) t S ub v a 1 v e s(10 »15) t @ 0 a 1 v e _ c t r1 

A COM block’s name, if it has one, will immediately follow the COM keyword, and will be set 
off with slashes, as shown above. The same rules used for naming variables and subprograms 
are used for naming COM blocks. 

Any context need only declare those COM blocks which it needs to have access to. If there are 
150 variables declared in 10 COM blocks, it isn’t necessary for every context to declare the 
entire set — only those blocks that are necessary to each context need to be declared. COM 
blocks with matching names must have matching definitions. As in parameter lists, matching 
COM blocks is done by position and type, not by name. 

There are several characteristics of COM blocks which distinguish them from parameter lists as 
a means of communications between contexts. 

• COM survives pre-run — In general, any numeric variable is set to 0, strings are set to the 
null string, and I/O path names are set to undefined after pushing the RUN key, or upon 
entering a subprogram. This is true of COM the first time the RUN key is pressed, but after 
COM block variables are defined, they retain their values until: 

1. SCRATCH A or SCRATCH C is executed, 

2. A statement declaring a COM block is modified by the user, 

3. A new program is brought into memory using the GET or LOAD commands which 
doesn’t match the declaration of a given COM block, or which doesn’t declare a 
given COM block at all. 

• COM blocks can be arbitrarily large — One limitation on parameter lists (both pass and 
formal parameter lists) is that they must fit into a single program line along with the line’s 
number, possibly a label, the invocation or subprogram header, and possibly (in the case of 
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a function) a string or numeric expression. Depending upon the situation, this can impose a 
restriction on the size of your parameter lists. 

COM blocks can take as many statements as necessary. COM statements can be inter¬ 
woven with other statements (though this is considered a poor practice). All COM state¬ 
ments within a context which have the same name will be part of the definition of that COM 
block. 

• COM blocks can be used for communicating between contexts that do not invoke each 
other — Information such as modes and states can be an integral part of communicating 
between contexts, even though those contexts don’t explicitly call each other. For instance, 
one routine might be responsible for setting the voltage range on a voltmeter, while 
another routine which may need to know what the current voltage range is in order to set 
up the scale on a graph properly. 

• COM blocks can be used to communicate between subprograms that are not in memory 
simultaneously — Similar to the case above, subprograms can communicate with each 
other through COM blocks even though combinations of LOADSUB/DELSUB may pre¬ 
clude their simultaneous presence in memory. 

• COM blocks can be used to retain the value of “local” variables between subprogram calls 

— In general, the variables used by a subprogram are discarded when the subprogram is 
exited. However, there are situations where it might be useful for a subprogram to “re¬ 
member” a value. A machine which tests capacitors in an incoming inspection department 
may require calibration after every 100 tests are performed. If the subprogram which does 
the testing has a way to count how many tests it has already performed (using a labeled 
COM block), then this task can be left to the testing routine, simplifying the rest of the 
system. 

• COM blocks allow subprograms to share data without the intervention of the main program 

— Subprogram libraries may consist of elaborate relationships of both programs and data 
structures. In many cases, a major portion of the data structures are only used for support 
of the task being performed, rather than being integral to the task itself. Thus the main 
program does not need to declare the supportive data structures. 

Examples of this situation might include data base management libraries (hashing tables 
may need to be maintained for accessing data quickly) or three dimensional graphics 
libraries (window, viewport, and clip information need to be kept, as well as object defini¬ 
tions and related transformations). 

Hints for Using COM Blocks 

Any COM blocks nee ded by your program must be resident in memory at prerun time (prerun 
is caused by pressing ( RUN ) , executing a RUN command, executing LOAD or GET from the 
progam, or executing a LOAD or GET from the keyboard and specifying a run line.) Thus if you 
want to create libraries of subprograms which share their own labeled COM blocks, it is wise to 
collect all the COM declarations together in one subprogram to make it easy to append them to 
the rest of the program for inclusion at prerun time. (The subprogram need not contain any¬ 
thing but the COM declarations.) 
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COM can be used to communicate between programs which overlay each other using LOAD or 
GET statements, if you remember a few rules. 

1. COM blocks which match each other exactly between the two programs will be preserved 
intact. “Matching” requires that the COM blocks are named identically (except blank 
COM), and that corresponding blocks have exactly the same number of variables de¬ 
clared, and that the types and sizes of these variables match. 

2. Any COM blocks existing in the old program which are not declared in the new program 
(the one being brought in with the LOAD or GET) are destroyed. 

3. Any COM blocks which are named identically, but which do not match variables and 
types identically, are defined to match the definition of the new program. All values 
stored in that COM block under the old program are destroyed. 

4. Any new COM blocks declared by the new program (including those mentioned above in 
#3 are initialized implicitly. Numeric variables and arrays are set to zero, strings are set to 
the null string, and I/O path names are set to undefined. 

The first occurrence in memory of a COM block is used to define or set up the block. Subse¬ 
quent occurrences of the COM block must match the defining block, both in the number of 
items, and the types of the items. In the case of strings and arrays, the actual sizes need be 
specified only in the defining COM blocks. Subsequent occurrences of the COM blocks may 
either explicitly match the size specifications by re-declaring the same size, or they may implicit¬ 
ly match the size specifications. In the case of strings, this is done by not declaring any size, just 
declaring the string name. In the case of arrays, this is done by using the ( * ) specifier for the 
dimensions of the array instead of explicitly re-declaring the dimensions. 

Consider the following COM block definition: 

10 COM / D urn -state/ INTEGER Ran3ejForfitat>N>REAL 

Delay >L a st d a t a(1:4 0) >S t a t us $ C 2 0] 

The following occurrence of the same COM block within a subprogram matches the COM block 
explicitly and is legal: 

2000 COM /Dum_state/ INTEGER Ran3e>Format>N»REAL 
Delay >L a s t d a t a(1:4 0) >S t a t us $ C 2 01 

The following block within a different subprogram uses implicit matching and is also legal: 

4010 COM /Duw-State/ INTEGER RanSe»Format»N»REAL 
Delay >Lastdata(*) > S t a t u s $ 

The following declaration is illegal, since it uses explicit size specifications on the array and 
string which do not match the original definition from line 10. 

5020 COM /Duffl_s t at e / INTEGER R an e t F o rw a t »N > RE AL 
Delay iLastdataf1;30) >Status$C153 

The following declaration is also illegal, since it violates the types set forth by the defining block. 

G010 COM /Duw_state/ Ran3e>Format>N>REAL 
Delay »Lastdata(*) tStatus$ 
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In general, the implicit size matching on arrays and strings is preferable to the explicit matching 
because it makes programs easier to modify. If it becomes necessary to change the size of an 
array or string in a COM block, it only needs to be changed in one statement, the one which 
defines the COM block. If all other occurrences of the COM block use the ( * ) specifier for 
arrays, and omit the length field in strings, none of those statements will have to be changed as 
a result of changing an array or string size. 

Context Switching 

As mentioned in the introduction to this chapter, a subprogram has its own context or state as 
distinct from a main program and all other subprograms. In between the time that a CALL 
statement is executed (or an FN name is used) and the time that the first statement in the 
subprogram gets executed, the computer performs a “prerun” on the subprogram. This “en¬ 
try” phase is what defines the context of the subprogram. The actions performed at subpro¬ 
gram entry are similar, but not identical, to the actual prerun performed at the beginning of a 
program. Here is a summary: 

• The calling context has a DATA pointer which points to the next item in the current DATA 
block which will be used the next time a READ is executed (assuming of course that a 
DATA block even exists in the calling program). This pointer is saved whenever a subpro¬ 
gram is called, and then the DATA pointer is reset to the first DATA statement in the new 
subprogram context. 

• The RETURN stack for any GOSUBs in the current context is saved and set to the empty 
stack in the new context. 

• The system priority of the current context is saved, and the called subprogram inherits this 
value. Any change to the system priority which takes place within the subprogram (or any 
of the subprograms which it calls in turn) is purely local, since the system priority is restored 
to its original value upon subprogram exit. This is an important consideration: If the 
subprogram is called as a result of an event-initiated GOSUB/CALL statement, any ON 
<event> GOTO/GOSUB/CALL/RECOVER condition set up in the called subprogram 
must have a higher priority assigned to it than the event responsible for the subprogram’s 
invocation. Otherwise, the event is guaranteed not to cause an end of line branch. 

• Any event-initiated GOTO/GOSUB statements are disabled for the duration of the subpro¬ 
gram. If any of the specified events occur, this will be logged, but no action will be taken. 
(The fact that an event did occur will be logged, but only once — multiple occurrences of 
the same event will not be serviced.) Upon exiting the subprogram, these event-initiated 
conditions will be restored to active status, and if any of these events occurred while the 
subprogram was being executed, the proper branches will be taken. 

• Any event-initiated CALL/RECOVER statements are saved upon entering a subprogram, 
but the subprogram still inherits these ON conditions since CALL/RECOVER are global in 
scope. However, it is legal for the subprogram to redefine these conditions, in which case 
the original definitions are restored upon subprogram exit. 

• The current value of OPTION BASE is saved, and the value for the subprogram (0 or 1, 
explicitly declared or defaulted) is used. 

• The current DEG or RAD mode for trigonometric operations and graphics rotations is 
saved. The subprogram will inherit the current DEG or RAD setting, but if it gets changed 
within the subprogram, the original setting will be restored when the subprogram is exited. 
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Variable Initialization 

Space for all arrays and variables declared is set aside, whether they are declared explicitly with 
DIM, REAL, or INTEGER, or implicitly just by using the variable. The entire value area is 
initialized as part of the subprogram’s prerun. All numeric values are set to zero, all strings are 
set to the null string, and all I/O path names are set to undefined. 

Subprograms and Softkeys 

ON KEYs are a special case of the event-initiated conditions that are part of context switching. 
They are special because they are the only <event> conditions which give visible evidence of 
their existence to the user through the softkeys labels at the bottom of the CRT. These key 
labels are saved just as the event conditions are, and the labels get restored to their original state 
when the subprogram is exited, regardless of any changes the subprogram made in the softkey 
definitions. This means the programmer doesn’t have to make any special allowances for 
re-enabling his keys and their associated labels after calling a subprogram which changes them 
— the language system handles this automatically. 

It is important to remember that the called subprogram inherits the softkey labels. All the keys 
are still active in some sense; ON KEY...CALL/RECOVER will cause their original program 
branches to take place immediately if the proper key is pressed, and ON KEY...GOTO/GOSUB 
will log the fact that a key is pressed until the subprogram is exited, at which time the proper 
branch will occur. This latter case may cause some consternation on the part of the user if he 
presses a softkey expecting immediate action and nothing happens since the key was tempor¬ 
arily disabled due to a called subprogram. If the called subprogram is expected to take a 
noticeably long time to execute, it might be a good idea to explicitly remove the labels from the 
disabled softkeys using the OFF KEY statement. Thus, the user won’t expect anything to 
happen as a result of pressing a softkey. This technique is also useful for guaranteeing that a 
given subprogram is not interrupted prematurely. (The DISABLE statement is useful for pre¬ 
venting program branches as a result of an event-initiated happening, although it will not turn 
off the softkey labels.) 

Subprograms and the RECOVER Statement 

The event-initiated RECOVER statement allows the programmer to cause the program to 
resume execution at any given place in the context defining the ON...RECOVER as a result of a 
specified event occurring, regardless of subprogram nesting. 

Thus, if a main program executes an ON...RECOVER statement (for example a softkey or an 
external interrupt from the SRQ line on an HP-IB), and then calls a subprogram, which calls a 
subprogram, which calls a subprogram, etc., program execution can be caused to immediately 
resume within the main program as a result of the specified event happening. 
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By way of illustration, consider the following example: 

Suppose you are performing an exhaustive component test on a circuit board. The program 
may be designed like so: 


MAIN 



B1 B2 B3 B4 B5 



CAPACITOR A CAPACITOR B RESISTOR A RESISTOR C 

When lunch break comes around, you may want to halt the current test so you can use the 
computer to play chess, or your boss might wander by and want to see the results of the rest of 
the tests performed this week. In either case, if the test program is nested three or four levels 
deep in subprograms, it might take a while for the test to complete. By defining a softkey to 
RECOVER to the main program, you can instantly terminate the test at any time, and make the 
computer available for something else. The RECOVER will discard anything being done in any 
of the subprograms between the context declaring the event-initiated RECOVER, and the 
subprogam being executed when the specified event occurs. 

Again, the DISABLE statement can be used within any subprograms in which it is critical not to 
allow interruptions. 

Live Keyboard 

Functions and subprograms can be called from live keyboard by the user. There are some 
restrictions: 

• Since variables cannot be created by the user from the keyboard (variables can only be 
defined by the program), it is legal to use only parameters that already exist in the current 
context. 

• Constants may be used in the pass parameter list. 

• When calling a SUB subprogram from the keyboard, the CALL keyword is not optional. 

Speed Considerations 

In some programs, speed is of the essence. In these cases, programmers will be reluctant to 
incur any unnecessary overhead in executing their task. There is a certain amount of overhead 
incurred in calling subprograms, although the overhead is fairly small, and shouldn’t be an 
impediment to the use of subprograms. (“Overhead” is loosely defined to be the time it takes to 
perform those activities which aren’t explicitly asked for by the user’s program, but which are 
still necessary to keep the user’s program running in a correct manner. The tasks discussed 
earlier under context switching are an excellent example of such overhead.) 
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Let’s look at how much time it takes just to get in and out of the subprogram regardless of the task 
being performed by the subprogram. (The times in this discussion are approximate and apply to the 
Model 226.) 

The time it takes to enter a subprogram depends upon the number of parameters being passed, 
the types of parameters being passed, and the number of variables declared local to the 
subprogram itself. To get in and out of a subprogram which has no parameters and which does 
nothing (in other words, a SUB followed by a SUBEND) takes 572 microseconds, meaning if 
you call it 1748 times, you’ll lose about a second. (By way of comparison, 572 microseconds is 
about what it takes to perform four floating point additions. To perform four floating point 
additions and store the result from each one in a variable will take about 1080 microseconds, or 
just over a millisecond.) 


Entry conditions 

Approximate execution speed 1 

No parameters 

572 (xsec. 

1 simple numeric 

+ 105 ixsec. 

1 simple string 

+ 128 (xsec. 

1 numeric array 

+ 141 ixsec. 

1 string array 

+ 141 (xsec. 

1 I/O path name 

+ 123 [xsec. 

OPTION BASE in sub 

+ 31 ixsec. 

REAL or INTEGER in sub 

+ 32 ixsec. 

1st numeric array declaration 

+ 18 fxsec. 

other numeric array declarations 

+ 11 ixsec. 

1st string array declaration 

+ 21 ixsec. 

other string array declarations 

+ 12 ixsec. 


As you can see from the table, subprograms are a bargain in terms of speed. The relatively small 
amount of overhead required for invoking a subprogram is more than made up for by the 
benefits to be derived. 


1 These speeds apply to computers without an HP 98635A, floating point. 
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Using Subprogram Libraries 

If you have a program which is quite large, along with sizable data arrays, you could run out of 
memory in your computer. But the program you’re working on just has to remain one program, 
and external factors prevent your reducing data array size. What to do? There are several 
options which address this problem. 

If you want to load a specific subprogram from a PROG file, you would use the 
LOADSUB <subprogram name> FROM statement. If you want to load all the subprograms 
from a specific PROG file, you would use the LOADSUB ALL FROM statement. And, if you 
wanted to see which subprograms are still missing or load all those still needed, you would use 
the LOADSUB FROM command. Note that this is a command, and not a statement. Therefore 
LOADSUB FROM cannot be invoked programmatically. 

Loading Subprograms One at a Time 

Suppose your program has several options to select from, and each one needs many subpro¬ 
grams and much data. All the options, however, are mutually exclusive; that is, whichever 
option you choose, it does not need anything that the other options use. This means that you 
can clean up everything you’ve used when you are through with that option. 

If all of your subprograms can be put onto one file, you can selectively retrieve them as needed 
with this sort of statement: 

LOADSUB Subp ro 3_1 FROM "SUBFILE" 

LOADSUB Subp ro 3_2 FROM "SUBFILE" 

LOADSUB FNNumeric_fn FROM "SUBFILE" 

LOADSUB FNStriri<r_functiori$ FROM "SUBFILE" 

Note that only one subprogram per line can be loaded with this form of LOADSUB. If, for any 
program option, you need so many subprograms that this method would be cumbersome, you 
could use the following form of the command. 

Loading Several Subprograms at Once 

For this method, you store all the subprograms needed for each option on its own file. Then, 
when the program’s user selects Program Option 1, you could have this line of code execute: 

LOADSUB ALL FROM "0PT1SUBFL" 

and if the user selects Option 2, 

LOADSUB ALL FROM "0PT2SUBFL" 

and so forth. 

There is one other form of LOADSUB, but it cannot be used programmatically. This is covered 
next. 

Loading Subprograms Prior to Execution 

In the LOADSUB FROM form, for which you need PDEV, neither ALL nor a subprogram name is 
specified in the command. This is used prior to program execution. It looks through the program in 
memory, notes which subprograms are needed (referenced) but not loaded, goes to the specified 
file and attempts to load all such subprograms. If the subprograms are found on the file, they are 
loaded into memory; if they are not, an error message is displayed and a list of the subprograms still 
needed but not found in the file is printed. 





User-Defined Functions and Subprograms 181 


This can be handy in two ways. The first and obvious way is that subprograms can be loaded 
quickly. The other way is this: suppose that you are developing a program and as you are 
coding, you realize you need a subprogram that does such-and-such. But your train of thought 
is chugging along so smoothly, you do not want to interrupt your coding of the routine you are 
working on to do the other little subprogram. But when the big one is done, you have forgotten 
all about coding the little one. If you suspect you’ve done this, the LOADSUB FROM command 
is very useful. Type a LOADSUB FROM command where the file name is a file on which you 
know there are none of the subprograms you need (perhaps a null PROG file). Of course, no 
subprograms will be loaded, but a list of those yet undefined will be printed. These are the ones 
you still need to code. Naturally, if you have already coded them and stored them somewhere, 
go get them. But if you haven’t, this is a simple way of listing those still to be entered. 

Any COM blocks declared in subprograms brought into memory with a LOADSUB by a 
running program must already have been declared. LOADSUB does not allow new COM 
blocks to be added to the ones already in memory. Furthermore, any COM blocks in the 
subprograms brought in must match a COM block in memory in both the number and type of 
the variables. Otherwise, an error occurs. 


Note 

If a main program is in a file referenced by a LOADSUB, it will not be 
loaded; only subprograms can be loaded with LOADSUB. Main 
programs are loaded with the LOAD command. 


With all this talk of loading subprograms from files, one question arises: How do you get the 
subprograms on the file? Easily: type in the subprograms you want to be on one file, and then 
STORE them onto the desired file name. You must use STORE and not SAVE, because the 
LOADSUB looks for a PROG-type file. If you can’t type in your subprograms error-free the first 
time (and who can?), what you can do is this: type in your program with all the subprograms it 
needs, and debug them. After storing everything on a file for safekeeping, delete what you 
do not want on the file, and STORE everything else on the subprogram file from which you will 
later do a LOADSUB. In this way, you know the subprograms will work when you load them. 

Deleting Subprograms Programmatically 

The utility of the LOADSUB commands would be greatly reduced if one could not delete subprog¬ 
rams from memory at will. So, there is a way to delete subprograms during execution of a 
program: DELSUB. If you want to delete only selected ones, you could type something like: 

DELSUB Sort-datatPrint_report_l >FNPo 1 >'_s o 1 u e 

If you are sure of the positioning of the subprograms in memory, here is a method of deleting 
whole groups of subprograms: 

DELSUB Print-report TO END 

You can combine these methods: 

DELSUB Sort_data»Print_re po rt»FNGet_name$ TO END 
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The subprograms to be deleted do not have to be contiguous in memory, nor does the order in 
which you specify the subprograms in a DELSUB statement have to be the order in which they 
occur in memory. The computer deletes each subprogram before moving on to the next name. 

If there are any comments after a FNEND or SUBEND, but before the next SUB or DEF FN, 
these will be deleted as well as the rest of the subprogram body. 

If the computer attempts to delete a nonexistent subprogram, an error occurs, and the DELSUB 
statement is terminated. This means that subprograms whose names occur after the error- 
causing one will not be deleted. 

A subprogram can be deleted only if it is not currently active and if it is not referenced by a 
currently active ON RECOVER/CALL statement. This means: 

1. A subprogram cannot delete itself. 

2. A subprogram cannot delete a subprogram that called it, either directly or indirectly. 
(Otherwise it wouldn’t have anywhere to return to when it finished!) 

Between the time that a subprogram is entered and the time it is exited, the computer keeps 
track of an activation record for that subprogram. Thus, if a subprogram calls a subprogram that 
calls a subprogram, etc., none of the subsequently-called subprograms can delete the original 
one or any of the ones in between because the system knows from the activation record that 
control will eventually need to return to the original calling context. A similar situation exists 
with active event-initiated CALL/RECOVER statements. As long as the possibility of the speci¬ 
fied event occurring exists, the system will not let the subprogram be deleted. In essence, the 
system will not let you execute two mutually-exclusive contradictory commands simul¬ 
taneously. 

Editing Subprograms 

Inserting Subprograms 

There are some rules to remember when inserting SUB and DEF FN statements: 

It is not possible to insert a DEF FN or SUB statement in the middle of the program. All DEF FN 
and SUB statements must be appended to the end of the program. If you want to insert a 
subprogram in the middle of your program because your prefer to see it listed in a given order, 
you must perform the following sequence: 

1. STORE the program. 

2. Delete all lines above the point where you want to insert your subprogram (refer to the 
DEL statement). 

3. STORE the remaining segment of the program in a new file. 

4. LOAD the original program stored in step 1. 

5. Delete all lines below the point where you want to insert your subprogram. 

6. Type in the new subprogram. 

7. Do a LOADSUB ALL from the new file in step 3. 
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With PDEV, the job is much easier: 

1. Write your new subprogram at the end of the program. 

2. Perform a MOVELINES command where: 

a. the Starting Line in the MOVELINES command is the line which you want to im¬ 
mediately follow your new subprogram, 

b. the Ending Line in the MOVELINES command is the line immediately prior to the 
SUB or DEF FN of the new subprogram, and 

c. The destination line is any line number greater than the highest line number current¬ 
ly in memory. 

In either case there is an optional final step. It is not required that you do a REN to renumber the 
program at this point, but often it is desirable to close up the void left in the program line 
numbering which resulted from the block of subprograms being moved to the end of memory. 

Deleting Subprograms 

It is not possible to delete either DEF FN or SUB statements with the delete line key unless you first 
delete all the other lines in the subprogram. This includes any comments after the SUBEND or 
FNEND. Another way to delete DEF FN and SUB statements is to delete the entire subprogram, up 
to, but not including, the next SUB or DEF FN line (if any). This can be done either with the DEL 
command, or with the DELSUB command. 

Merging Subprograms 

If you want to merge two subprograms together, first examine the two subprograms carefully to 
insure that you don’t introduce conflicts with variable usage and logic flow. If you’ve convinced 
yourself that merging the two subprograms is really necessary, here’s how you go about it: 

1. SAVE everything in your program after the SUB or DEF statement you want to delete. 

2. Delete everything in your program from the unwanted SUB statement to the end. 

3. GET the program segment you saved away in step 1 back into memory, taking care to 
number the segment in such a way as not to overlay the part of the program already in 
memory. 

Once again, with PDEV, your job is greatly simplified: 

Execute a MOVELINES command in which you move everything from one subprogram— 
excluding the SUB/DEF FN and SUBEND/FNEND statements—into the desired position in 
the other subprogram. If there are any declarative statements in the moved code, you will 
probably want to move those up next to the declarative statements in the receiving code. Don’t 
forget to go back to the place where the code came from and delete the SUB/DEF FN statement 
and the SUBEND/FNEND statements. 

SUBEND and FNEND 

The SUBEND and FNEND statements must be the last statements in a SUB or function sub¬ 
program, respectively. These statements don’t ever have to be executed; SUBEXIT and RE¬ 
TURN are sufficient for exiting the subprogram. (If SUBEND is executed, it will behave like a 
SUBEXIT. If FNEND is executed, it will cause an error.) Rather, SUBEND and FNEND are 
delimiter statements that indicate to the language system the boundaries between subprog¬ 
rams. The only exception to this rule is the comment statements (either REM or !), which are 
allowed after SUBEND and FNEND. 
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Notice that we haven’t worried about the tree structure yet. This is because the tree is only used 
to provide ordering information to be used in printing out the report. Since the tree is not 
necessary except for the report, we’ll let the report subprogram worry about it. The variables 
Max and Howmany are introduced for the sake of flexibility. It is possible that the department 
may have to hire more people at some time in the future, or that some people may leave the 
company or accept jobs in other departments. In this case, the program will have to be changed 
to allow for a different number of people. By making the maximum number of people, and the 
actual number of people, variables instead of constants, modifying the program becomes very 
easy. 


Also, notice that each of the subprograms has been “stubbed in”. The reason for doing this is 
that you can immediately run the program to test the communications between modules. So 
far, the program will not do anything, but it does allow you to make sure that your pass 
parameter lists match the formal parameter lists in the number and types of parameters. Furth¬ 
ermore, this process can be repeated every step of the way. As each subprogram is designed, 
the modules called by it can be “stubbed in” in a similar fashion, insuring that the parameter 
lists and communications paths are well defined and properly implemented at every level of 
your design. The most difficult part of testing your program is done as the program is being 
designed. 


Let’s step down to the next level of the design and consider each of the subprograms men¬ 
tioned above: 

90 SUB Input_dat a(Name$(*) ^INTEGER Units**) »REAL Failures**)^INTEGER M a x * H o w m a 
n y ) 

91 DIM Wh i ch$C3] 

92 INPUT "New Data or Old?"#Which$ 

93 IF Which$="New" THEN 

94 En t e r_n e w(N am e $(*) >Unit s * *) »Failures(*) * Max *H o wm an y) 

95 ELSE 

9G E d i t _ o 1 d * N a m e $ * * ) >Unit s * *) ^Failures**) >M a x * Howm an y) 

97 END IF 

100 SUBEND 

101 ! 

110 SUB Store_data(Name$(*) ,INTEGER Units(*) »REAL Fai1ures(*) »INTEGER MaxtHowma 
n y ) 

111 Setup-fi1e(@Fi 1 e ) 

112 OUTPUT @File5Name$(*) »Units<*) ^Failures**) 

113 ASSIGN @Fi1e TO * 

120 SUBEND 

121 ! 

130 SUB Report<Name$<*) ^INTEGER Units(*) tREAL Failures**)^INTEGER MaxtHowwany) 

132 OPTION BASE 1 

133 INTEGER Root tl >Whic h f i e 1 d 

134 ALLOCATE INTEGER Tree(Howmany»2) 

135 Init_tree(Root >T ree(*)) 

13S Ask: INPUT "Which field (1= Name»2 = Units»3 = Fai1ures)?" ♦ Whichf i e 1 d 

137 IF WhichfieldCl OR Whichfield>3 THEN Ask 

138 FOR 1=2 TO Howmany 

139 SELECT Which_field 

140 CASE 1 

141 BuildstrinS(Root»Tree(*) >I>Name$(*)) 

142 CASE 2 

143 Buildnum(Root»Tree(*) >I»Units**)) 

144 CASE 3 

145 Bu i 1 d nurn(Ro o t ♦ T r e e(*) t 1 »F ai1ure s(*) ) 

14S END SELECT 

148 NEXT I 

149 Inorder(Root»T r e e * * ) *N am e $(*) * Units**) ^Failures**)) 

150 SUBEND 
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Here we haven’t gone through the exercise of providing the dummy subprograms, though in 
actual practice we would. In lines 94 and 96 of the data entry program, we see two more 
subprograms that need to be designed. The module for entering new data from the keyboard 
will be straightforward and need not be considered in further detail for this example. The 
module for editing old data will involve loading a set of data from the diskette and then allowing 
the user to modify those values. This will involve a little more detail and perhaps another level 
of subprograms, but the techniques to be used are still straightforward enough not to demand 
further attention here. 

Line 111 calls for a module to setup a data file to store the data on, and passes an I/O path 
name back out that’s ready for use. This means that the subprogram must: 

1. Ask the user for a file 

2. Create the file if necessary 

3. ASSIGN it for use 

The Report subprogram is by far the most interesting one in this example, since it deals with the 
initialization, construction, and traversal of a binary tree, as discussed above. The Init_tree 
subprogram called in line 135 simply initializes the root node’s (first element, remember) 
subtrees to be empty. Subsequently, the Buildstring subprogram called in line 140 simply 
enters the Ith string in the Name$(*) array into the structure of T re e ( * ), assuming that the 
user asked for the report to be sorted by N a m e $ ( *). Similarly, if the user wanted either 
Un i t s ( * ) or Fail u rest*) to be the sort key, then the Buildnum subprogram (called in 
lines 143 and 145) would be used to construct the tree. 

Finally, the Inorder subprogram traverses the structure in “inorder” once the tree has been 
built. “Inorder” simply means that every node is printed in between that node’s subtrees. This 
traversal mechanism, as you will see, is quite short, and is a truly elegant expression of the task 
being performed. 
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Here are the Init_tree, Buildstring, and Inorder subprograms (Buildnum is so similar to Build¬ 
string that it isn’t necessary to list it too): 


200 

210 

220 

230 

240 

250 

2S0 

270 

280 

281 

290 

300 

310 

320 

330 

340 

350 

351 
380 
370 
380 
390 
400 
410 
420 
430 
440 
450 
480 
470 

480 

481 
490 
) 

500 

510 

520 

530 

540 

550 

580 


SUB Init_tree(INTEGER Root >T ree(*)) 
COM /Tree/ INTEGER Nil »Le f t »Ri0ht 
Ni 1=0 
Left=l 
R i s h t = 2 
Ro o t = 1 

T ree(Root *Left)=Nil 
T ree(Root»Ri$ht)=Nil 
SUBEND 


SUB Bui ldst rin*< INTEGER Root >Tree (*) »I n d e x »A $ ( * ) ) 
COM /Tree/ INTEGER Ni1 ,Left >Ri*ht 
IF A $(Index )<=A$(Root) THEN 

IF T ree(Root #Left)=Nil THEN 
Tree(Root»Left)=Index 
T ree(Index»Left)=Nil 
T ree(Index >RiSht)=Nil 


Search the left subtree 
Once a leaf is found (link is 
nil) point to the new n ode 
(Index) with the leaf's left 
pointer and set up the new 
node as a leaf* 


ELSE 


Buildstrinsf(Tree(Root»Left) t T r e e ( * ) 1 1 n d e x t A $(*)) 


END IF 
ELSE 

IF Tree(Root»Ritfht)=Ni1 THEN 
T ree(Root> R i S h t ) = I n d e x 
T r e e(In d e x »Left)=Nil 
Tree(Index*Risht)=Nil 
ELSE 


Search the risht subtree 
Once a leaf is found (link is 
nil) point to the new node 
from the risht pointer instead 
of the left* 


BuildstrinS(Tree(Root»RiSht) »T ree(*) * I n d e x * A $ ( * ) ) 
END IF 
END IF 
SUBEND 

i 


SUB Inorder(INTEGER Root»Tree(*) »Name$(*)#INTEGER Uni t s (*) tREAL Failures**) 


COM /Tree/ INTEGER Nil *Left »RiSht 
IF RootONil THEN 

Ino rde r(T ree (Root >Lef t) t T r e e ( * ) * N a m e $ ( * ) »U n i t s ( * ) ^Failures**)) 
PRINT Name$(Root) »Uri its (Root) »Fa i 1 u re s ( Ro o t) 

Inorder(Tree(Root»Riaht) >T ree(*) t N a m e $(*) *U nit s(*) >Failures(*)) 
END IF 
SUBEND 


Let’s step through a sample input stream and see how the tree is constructed using the Build¬ 
string subprogram: 

N a m e $ ( * ) 

1. Perriwinkle 

2. Jones 

3. Smith 

4. Snodgrass 

5. Figby 

6. Brown 

7. Thompson 

8. Richards 

9. Hughes 

10. Davenport 
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Tree structure after Init_tree is executed 


(i) 


Perriwinkle 



Tree structure after subsequent insertions into the tree by the Buildstring 
subprogram: 
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These three subprograms illustrate several points that were discussed in this chapter: 

They share a labeled COM block which is not declared in the main program, nor in the Report 
program. The information in the COM block was only relevant to the the three subprograms, 
yet the programs never called each other — they were all called from Report. 

Both the Inorder and Buildstring subprograms are recursive — they call themselves. This 
technique was an appealing way to solve the problem because of the recursive nature of the 
data structure. (Many types of data structures are recursively defined.) 

The use of subprograms to build and traverse the data structure turned out to execute faster 
than a sort subprogram which physically moved the items in the three fields into a given order 
based on sorting one of the arrays. (The difference was about 40% using Donald Shell’s 
algorithm 5 .) 

The method of Top-Down Design led to the orderly design, creation, and testing of each 
subprogram, module by module, layer by layer. Communication paths and data structures/ 
types were forced to be clearly defined at each step of the way. 
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Data Storage and Retrieved 


Chapter 

7 


This chapter describes some useful techniques for storing and retrieving data. First we describe 
how to store and retrieve data that is part of the BASIC program. With this method, DATA 
statements specify data to be stored in the memory area used by BASIC programs; thus, the 
data is always kept with the program, even when the program is stored in a mass storage file. 
The data items can be retrieved by using READ statements to assign the values to variables. 
This is a particularly effective technique for small amounts of data that you want to maintain in a 
program file. 

For larger amounts of data, mass storage files are more appropriate. Files provide means of storing 
data on mass storage devices. The two types of data files available with Series 200 computers — 
ASCII and BDAT files — are described in this chapter. A number of different techniques for 
accessing data in BDAT files are described in detail. General disc structure is also described. 

Series 200 computers can use a number of different mass storage devices, including disc drives 
(internal and external), SRM systems, and magnetic bubble memories. This chapter gives 
guidelines for accessing many kinds of devices. 
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Storing Data in Programs 

This section describes a number of ways to store values in memory. In general, these techni¬ 
ques involve using program variables to store data. The data are kept with the program when it 
is stored on a mass storage device (with STORE and SAVE). These techniques allow extremely 
fast access of the data. They provide good use of the computer’s memory for storing relatively 
small amounts of data. 

Storing Data in Variables 

Probably the simplest method of storing data is to use a simple assignment, such as the 
following LET statements: 

100 LET Cm_per_inch=2.54 
110 Inch_pe r_cm=1/Cm_pe r_inch 

The data stored in each variable can then be retrieved simply by specifying the variable’s name. 
This technique works well when there are only a relatively few items to be stored or when 
several data values are to be computed from the value of a few items. The program will execute 
faster when variables are used than when expressions containing constants are used; for inst¬ 
ance, using the variable Inch_pe r_cm in the preceding example would be faster than using 
the constant expression 1/2.54. In addition, it is easier to modify the value of an item when it 
appears in only one place (i.e., in the LET statement). 

Data Input by the User 

You also can assign values to variables at run-time with the INPUT and LINPUT statements as 
shown in the following examples. 

100 INPUT "Type in the value of X> please." .Id 


200 DISP "Enter the value of X. Y> and 2." 

10 LINPUT Responses 

Note that with this type of storage, the values assigned to the corresponding variables are not 
kept with the program when it is stored; they must be entered each time the program is run. 
This type of data storage can be used when the data are to be checked or modified by the user 
each time the program is run. As with the preceding example, the data stored in each variable 
can then be retrieved simply by specifying the variable’s name. 

Using DATA and READ Statements 

The DATA and READ statements provide another technique for storing and retrieving data 
from the computer’s read/write (R/W) memory. The DATA statement allows you to store a 
stream of data items in memory, and the READ statement allows you retrieve data items from 
the stream. 
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You can have any number of READ and DATA statements in a program in any order you want. 
When you RUN a program, the system concatenates all DATA statements in the same context 
into a single “data stream.” Each subprogram has its own data stream. The following DATA 
statements distributed in a program would produce the following data stream. 

100 DATA 1 >A >50 


200 DATA “BB" >20 >45 


300 DATA X»Y>77 


DATA STREAM: 


1 

A 

50 

BB 

20 

45 

X 

Y 

77 


As you can see from the example above, a data stream can contain both numeric and string 
data items; however, each item is stored as if it were a string. 

Each data item must be separated by a comma and can be enclosed in optional quotes. Strings 
that contain a comma, exclamation mark, or quote mark must be enclosed in quotes. In 
addition, you must enter two quote marks for every one you want in the string. For example, to 
enter the string QUOTE”QUO”TE into a data stream, you would write: 

100 DATA "QUOTE""QUO""TE" 

To retrieve a data item, assign it to a variable with the READ statement. Syntactically, READ is 
analogous to DATA; but instead of a data list, you use a variable list. For instance, the state¬ 
ment: 

100 READ X »Y >Z$ 

would read three data items from the data stream into the three variables. Note that the first two 
items are numeric and the third is a string variable. 

Numeric data items can be READ into either numeric or string variables. If the numeric data 
item is of a different type than the numeric variable, the item is converted (i.e., REALs are 
converted to INTEGERS, and INTEGERS to REALs). If the conversion cannot be made, an 
error is returned. Strings that contain non-numeric characters must be READ into string vari¬ 
ables. If the string variable has not been dimensioned to a size large enough to hold the entire 
data item, the data item is truncated. 
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The system keeps track of which data item to READ next by using a “data pointer”. Every data 
stream has its own data pointer which points to the next data item to be assigned to the next 
variable in a READ statement. When you run a program segment, the data pointer is placed 
initially at the first item of the data stream. Every time you READ an item from the stream, the 
pointer is moved to the next data item. If a subprogram is called by a context, the position of the 
data pointer is recorded and then restored when you return to the calling context. 

Starting from the position of the data pointer, data items are assigned to variables one by one 
until all variables in a READ statement have been given values. If there are more variables than 
data items, the system returns an error, and the data pointer is moved back to the position it 
occupied before the READ statement was executed. 

Examples 

The following example shows how data is stored in a data stream and then retrieved. Note that 
DATA statements can come after READ statements even though they contain the data being 
READ. This is because DATA statements are linked during program pre-run, whereas READ 
statements aren’t executed until the program actually runs. 


10 

DATA 

November*26 

20 

READ 

M o n t h $ t Day »Year$ 

30 

DATA 

1981 *"The date i s H 

40 

READ 

St r$ 

50 

Print 

St r$ 9 Mon t h$ t Day t Ye a r$ 

GO 

END 


The 

date 

is November 2G 1981 


Storage and Retrieval of Arrays 

In addition to using READ to assign values to string and numeric variables, you can also READ 
data into arrays. The system will match data items with variables one at a time until it has filled a 
row. The next data item then becomes the first element in the next row. You must have enough 
data items to fill the array or you will get an error. In the example below, we show how DATA 
values can be assigned to elements of a 3-by-3 numeric array. 


10 

□ PTI 

ON BASE 1 


20 

DIM 

Example ( 3 »3 ) 


30 

DATA 

1 * 2 >3 ,4 

>5 *6 

il * 8 * 9 * 10*11 

40 

READ 

Example < 

;*> 


50 

PRINT USING ' 

' 3 (K 

* X ) * / " 5 E x a m p 1 e ( * ) 

GO 

END 





1 

9 

3 

4 

5 

G 

7 

8 

9 


The data pointer is left at item 10; thus, items 10 and 11 are saved for the next READ 
statement. 
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Moving the Data Pointer 

In some programs, you will want to assign the same data items to different variables. To do this, 
you have to move the data pointer so that it is pointing at the desired data item. You can 
accomplish this with the RESTORE statement. If you don’t specify a line number or label, 
RESTORE returns the data pointer to the first data item in the data stream. If you do include a 
line identifier in the RESTORE statement, the data pointer is moved to the first data item in the 
first DATA statement at or after the identified line. The example below illustrates how to use the 
RESTORE statement. 


100 

DIM Array 1(1:3) 

! Dimensions a 3-element 

array* 

110 

DIM A r ray2(0:4) 

! Dimensions a 5-element 

array* 

120 

DATA 1 >2 *3 >4 

! Places 4 items in stream* 

130 

DATA 5 >BH 

! Places 3 items in stream* 

140 

READ A >C 

! Reads first 3 items in 

stream* 

1 50 

READ A r ra y2 < *) 

! Reads next 5 items in 

st ream* 

ISO 

DATA 8 *3 

! Places 2 items in stream* 

170 


j 


180 

RESTORE 

! Re-positions pointer to 1st item* 

190 

READ Array 1<*) 

! Reads first 3 items in 

stream* 

200 

RESTORE 140 

! Moues data pointer to 

item n 8“ ♦ 

210 

READ D 

! Reads M 8". 


220 


1 


230 

PRINT "Array 1 c or. t a i n s : " 5 A r r ay 1 ( * ) 5 " " 


240 

PRINT "A r ray2 contains5Array2(*)! " " 


250 

PRINT "A >B tC >D 

equal:" !A SBiC 5D 


260 

END 




Array 1 

contains: 

1 

2 

3 

A r r a y 2 

contains: 

4 

5 

S 7 8 

A tC >D 

equal: 1 

2 

3 

8 
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Mass Storage Tutorial 

The rest of this chapter describes the second general class of data storage and retrieval methods 
— that of using mass storage devices. This material is broken up into two main parts. The first 
part presents a general tutorial regarding disc and file structures. The second part presents 
techniques for accessing mass storage devices and files with BASIC statements. If you are 
anxious to “get going,” turn to “Mass Storage Techniques” (about 10 pages ahead) and refer 
back to the tutorial as needed. 


What Is Mass Storage? 

As the adjective “mass” suggests, mass storage devices are data-storage devices which are 
generally capable of storing “large” amounts of data. Just how much data constitutes a large 
amount depends on the device itself. Most mass storage devices are capable of storing on the 
order of hundreds of thousands to several million items. 

Besides having the ability to store data, mass storage devices are capable of providing means for 
keeping data organized so that logical groups may be accessed systematically and efficiently. Data 
items are organized into logical groups of data known as files, a file is merely a collection of data 
items. Mass storage volumes are composed of one or more files. On most HP mass storage devices, 
a volume consists of all files on the mass storage media-, mass storage media are the actual physical 
means by which data are stored. For instance, the media used by the internal drives of the Model 
226 and Model 236 consist of magnetic particles on a plastic disc which can be magnetized to store 
data. 

The Structure of Model 226/236 Discs 

This section describes the specific structure of discs used with built-in Model 226/236 drives. This 
specific structure is similar to the general structure of all HP discs. Some of the information in this 
section (directory format and disc interleave) is useful to the advanced programmer; however, it is 
not a prerequisite for general mass storage usage. 

Most HP mass storage devices use magnetic discs as their storage media. Magnetic discs possess 
features of both records and recording tape. Like a record, it is circular, has tracks (most have tracks 
on both sides), and rotates. Like a tape, data is written and read by an electromagnetic head. 

The internal disc drive(s) of the Model 226 and 236 use 5.25-inch diameter, flexible disc media. 
These flexible discs have two usable sides with 33 tracks on each side. Each track is further divided 
into sixteen sectors, each of which contain 256 contiguous bytes of data. A track, therefore, 
contains 4096 bytes, and an entire disc is capable of holding over 270,000 bytes of information. 
However, some of this space is reserved for system use and cannot be used for data storage. 

In addition to the internal disc drive(s), you can also use external drives with your computer. There 
are several types of drives that are compatible with HP Series 200 computers. Some mass storage 
devices use the same 5.25-inch diameter flexible discs as the internal drives, while others use 
3.5-inch or 8-inch flexible discs and/or hard discs. We describe how to access external drives later in 
this chapter. 
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As previously mentioned, information is stored on a disc by placing it in a file. A file is a logical 
unit that occupies a certain number of sectors on the storage media. Files can be used to store 
either programs or data. In this chapter, we are concerned primarily with data files, although 
parts of the discussion relate to program files as well. 

When you SAVE a program, the system automatically creates an ASCII file of sufficient size to 
store the program in its “source form” — as ASCII characters. When you create a data file with 
the CREATE ASCII or CREATE BDAT statements, you give it a name and specify how much 
disc space should be reserved for it. In general, the only limit to the size of a file is the amount of 
contiguous, unreserved space left on the media, since files cannot span disc volumes. 

Let’s take a brief look at how the the system accesses the information in the file. (More 
complete details of file access will be described later.) In order to access the information in a file, 
you assign an I/O path name to the file’s name. When this I/O path is used to send and receive 
information to and from the file, the system handles the details of the access operation. The 
important point here is that the system always reads and/or writes an entire sector of data 
whenever a disc is accessed. For instance, if only one byte of data is to be written in a file, an 
entire sector must be read, the single byte changed, and the (modified) sector re-written. 
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Disc Interleave 

The INITIALIZE statement allows you to specify an interleave factor. Interleaving a disc causes the 
sectors on each track to be numbered according to a specified interval. An interleave factor of 1 
causes sectors to be numbered consecutively. A factor of 2, on the other hand, tells the system to 
skip every other sector. The following drawing shows how these interleaves are implemented on 
the 5.25-inch flexible discs used by the Model 226 and Model 236 internal drives. 



A track of a disc with A track of a disc with 

interleave factor of 1. interleave factor of 2. 

The system numbers each sector on each track according to the pattern specified by the 
interleave factor. All tracks on a disc have the same interleave factor. 

The purpose of disc interleave is to increase data-transfer rates, as demonstrated in the follow¬ 
ing example. Suppose that we are entering data from a disc; suppose also that the data have 
formats which are different from the computer’s internal data formats. Consequently, after each 
item is read, the computer must change the data from the disc’s data format to the computer’s 
internal data format. Note that during this processing time the disc is still spinning. 

If the processing of all items in a sector takes more time than the disc drive takes to reach the 
next sector, the computer must wait (slightly longer than one full revolution of the disc) until the 
next sector again comes under the head. By interleaving a disc, you can allow for this proces¬ 
sing time, which results in faster transfer rates. 

The default interleave factor for each type of drive is designed to give maximum transfer rates for 
LOAD and STORE operations (and for OUTPUT and ENTER of numeric arrays using BDAT files 
with the FORMAT OFF attribute). The default interleave factor is 1 for internal drives of the Model 
226 and Model 236. For other HP drives, the optimum interleave may differ. All default interleave 
factors are shown later in this chapter. 
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If you use the default interleave factors, you should be aware that discs initialized on one drive may 
show a performance degradation if used on another drive. For instance, suppose you INITIALIZE a 
disc on the internal drive (default interleave factor is 1) and then use that disc in an HP 82901 drive 
(default interleave factor of 4). You probably will get slower transfer rates than if the default 
interleave for the HP 82901 had been used. In summary, if you need maximum transfer rates, 
experiment to determine the optimal interleave for your particular application. 

When estimating optimal interleave factors, it is better to use a factor too large than one too 
small. For instance, suppose that an interleave of 2 is optimal for a particular operation. If an 
interleave of 1 is improperly chosen, the operation is slowed down approximately by a factor of 
eight. On the other hand, using an interleave of 3 only slows the operation approximately by a 
factor of two. If in doubt about which of two interleave factors is optimal for a particular 
situation, it is generally better to choose the larger. 

Volume Label 

The first sector on every disc contains information about the disc volume. It contains the name 
of the volume, the starting address of the directory, and the length of the directory. The figure 
below shows the values and locations of this information for LIF-compatible discs. 


WORD: 01 23456789 10-M27 





VOLUME DIRECTORY 
LABEL START 

ADDRESS = 
SECTOR 2 


DIRECTORY DECIMAL 

LENGTH = 0’s 

14 


DECIMAL DECIMAL DECIMAL 

-32768 4096 0 


Directory 

A directory is an index of all files on the disc. Every disc volume has a directory. On Model 226/236 
internal disc volumes initialized with BASIC, the directory occupies sectors 2 thru 15. Other discs or 
discs initialized in other languages may have a different directory size. However, the general 
structure of the directory entries is the same. In this directory, there is a 16-word entry for every file; 
each directory sector can thus hold 8 entries. Since this directory contains 14 sectors, it can hold up 
to 112 entries; therefore, the limit on the number of files in a volume is 112. The figure below shows 
the format of a directory entry. 


WORD: 


0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 



FILE NAME 


STARTING 

SECTOR 


CREATION 

TIME 


FILE FILE VOLUME PROTECT DEFINED 

TYPE LENGTH NUMBER CODE RECORD 

LENGTH 

















































202 Data Storage and Retrieval 


File Name — Every file is given a name when it is created. File names can be up to 10 
characters long. 

File Type — BASIC supports five file types: ASCII, BDAT, BIN, PROG and SYSTM. We 
discuss BDAT and ASCII data type files later in this chapter. 

Starting Sector — The address of the file’s first sector. Files always start at the beginning of a 
sector. 

Length of File — Length is given in sectors. If a file ends in the middle of a sector, the whole 
sector is counted. 

Time of Creation — Not used. Entry is filled with zeros. 

Volume Number — The least significant 15 bits give the volume number, which is always 1 on 
Series 200 computers. The most significant bit tells whether the file is continued in another 
volume (0 for yes, 1 for no). Since files on these computers cannot span volumes, this bit is 
always set to 1. 

Protect Code — Any BDAT, BIN or PROG type file can be given a two-character protect code 
with the PROTECT statement. ASCII and SYSTM type files cannot be protected. This word is 
always 0 with ASCII files; it has a different use with SYSTM files. Protect codes are discussed 
later in this chapter. 

Defined-Record Length — If a file is of BDAT type, it can have defined records from 1 thru 
65 534 bytes long. This is described in detail later in this chapter. Defined records in all other 
file types are always one sector (256 bytes) long. The defined record length is encoded into 
word 15 as length/2. (If length = 1, then word 15 = 0.) This word is always 0 with ASCII files; it 
has a different use with SYSTM files. 
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The Structure of Data Files 

There are two file types that you can use to store data: BDAT and ASCII. BDAT files have 
several advantages: they allow more flexibility in data formats and access methods, allow faster 
transfer rates, and are generally more space-efficient than ASCII data files. They can be ran¬ 
domly or serially accessed, and they allow data to be stored in either ASCII format, internal 
format, or a specialized format (defined by the user with IMAGE statements). 

ASCII files allow only serial access and only ASCII format. They have these advantages: the files 
are compatible with other HP computers that support this file type, the format provides very 
compact storage for string data, and there is no chance of reading the contents into the wrong data 
type (a problem for BDAT files). The full name of ASCII files is “LIF ASCII”. LIF stands for Logical 
Interchange Format, a directory and data storage format that is used by many HP computer 
divisions. Understanding the characteristics of each file type will help you choose the best one for 
your specific application. 

BDAT Files 

BDAT files are designed to be storage-space efficient, have high data-transfer rates, and allow 
both random and serial access. Random access means that you can directly read from and write 
to any record within the file, while serial access only permits you to access the file from the 
beginning. Serial access can waste a lot of time if you’re trying to access data at the end of a file. 
On the other hand, if you want to access the entire file sequentially, you are better off using 
serial access than random access. BDAT files can be accessed both randomly and serially, while 
ASCII files can only be accessed serially. 

BDAT files allow you to store and retrieve data using internal format, ASCII format, or user- 
defined formats. With internal format, items are represented with the same format the system 
uses to store data in internal computer memory 1 . With ASCII format, items are represented by 
ASCII characters. User-defined formats are implemented with programs that employ OUTPUT 
and ENTER statements that reference IMAGE specifiers. Complete descriptions of ASCII and 
user-defined formats are given in Chapters 4, 5, and 10 of BASIC Interfacing Techniques. 

In most applications, you will use internal format for BDAT files. Unless we specify otherwise, 
you can assume that when we talk about retrieving and storing data in BDAT files, we are also 
talking about internal format. This format is synonymous with the FORMAT OFF attribute, 
which is described later in this chapter. 

Because BDAT files use almost the same format as internal memory, very little interpretation is 
needed to transfer data from the computer to a BDAT file, or vice versa. BDAT files, therefore, 
not only save space but also time. 

Data stored in internal format in BDAT files require the following number of bytes per item: 

INTEGER 2 bytes 

REAL 8 bytes 

String 1 byte per character (plus 1 pad byte if the string length is an 

odd number), plus a 4-byte length header 


1 Actually, the format for BDAT files is slightly different than internal format. Instead of using a 2-byte length header for strings, BDAT files use 
a 4-byte length header. Besides this, the two formats are identical, so we refer to both as “internal”. 
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INTEGER numbers are represented in BDAT files by using a 16-bit, two’s-complement nota¬ 
tion, which provides a range —32 768 thru 32 767. If bit 15 (the MSB) is 0, the number is 
positive. If bit 15 equals 1, the number is negative; the value of the negative number is obtained 
by changing all ones to zeros, and all zeros to ones, and then adding one to the resulting value. 

Examples 


Binary Representation 

Decimal Equivalent 

00000000 00010111 

23 

11111111 11101000 

-24 

10000000 00000000 

-32768 

01111111 11111111 

32767 

1111111111111111 

-1 

00000000 00000001 

1 

00100011 01000111 

9031 

11011100 10111001 

-9031 


REAL numbers are stored in BDAT files by using their internal format: the IEEE-standard, 
64-bit, floating-point notation. Each REAL number is comprised of two parts: an exponent (11 
bits), and a mantissa (53 bits). The mantissa uses a sign-and-magnitude notation. The sign bit 
for the mantissa is not contiguous with the rest of the mantissa bits; it is the most significant bit 
(MSB) of the entire eight bytes. The 11-bit exponent is offset by 1 023 and occupies the 2nd 
through the 12th MSB’s. Every REAL number is internally represented by the following equa¬ 
tion. (Note that the mantissa is in binary notation): 


mantissa sign exponent - 1023 

-1 x 2 


X 1. 


mantissa 


The figure below shows how the real number “1/3” would be stored in a BDAT file. 


Byte 

Decimal value 
of character 

Binary value 
of characters 


1 

2 

3 

4 


8 

63 

213 

85 

85 


85 

00111111 

11010101 

01010101 

01010101 


01010101 


mantissa sign exponent 


mantissa 
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String data are stored in BDAT files in their internal format (plus two additional, leading bytes 
of length header, which are always 0 for Series 200 computers). Every character in a string is 
represented by one byte which contains the character’s ASCII code. The four-byte length 
header contains a value that specifies the length of the string. If the length of the string is odd, a 
pad character is appended to the string to get an even number of characters; however, the 
length header does not include this pad character. 

Examples 

If stored as a string value, the number “45” would be: 

00000000 00000000 00000000 00000010 00110100 00110101 

Length = 0002 (binary) ACSII 52 ASCII 53 

The string “A” would be stored: 

00000000 00000000 00000000 00000001 01000001 00100000 

Length = 0001 (binary) ASCII 65 ASCII 32 


In this case, the space character (ASCII code 32) is used as the pad character; however, not all 
operations use the space as the pad character. 

When using the ASCII data format for BDAT files, all data items are represented with ASCII 
characters. With user-defined formats, the image specifiers referenced by the OUTPUT or 
ENTER statement are used to determine the data representation. Using both of these formats 
with BDAT files produce results identical to using them with devices. The entire subject is 
described fully in Chapters 4, 5, and 10 of BASIC Interfacing Techniques. The topic of adv¬ 
anced transfer techniques for BDAT files is described in Chapter 11 of the same manual. Refer 
to this material after reading “Mass Storage Techniques” later in this chapter. 
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ASCII Files 

You have already been introduced to ASCII files as a way to SAVE programs. ASCII files can 
also be used to store data. In an ASCII file, every data item, whether string or numeric, is 
represented by ASCII characters; one byte represents one ASCII character. Each data item is 
preceded by a two-byte length header which indicates how many ASCII characters are in the 
item. However, there is no “type” field for each item; data items contain no indication (in the 
file) as to whether the item was stored as string or numeric data. For instance, the number 456 
would be stored as follows in an ASCII file: 


0 

4 


4 

CJl 

CD 


d 


LENGTH ASCII 
HEADER = CODES 
BINARY 4 


Note that there is a space at the beginning of the data item. This signifies that the number is 
positive. If a number is negative, a minus sign precedes the number. For instance, the number 
- 456, would be stored as follows: 


0 


4 


4 


5 


6 


LENGTH ASCII 
HEADER = CODES 
BINARY 4 


If the length of the data item is an odd number, the system “pads” the item with a space to 
make it come out even. The string “ABC”, for example, would be stored as follows: 


0 

3 

A 

B 

C 

(pad) 


d 




LENGTH ASCII 

HEADER = CODES 
BINARY 3 


There is often a relatively large amount of overhead for numeric data items. For instance, to 
store the integer 12 in an ASCII file requires the following six bytes: 


0 

3 


1 

2 

(pad) 





LENGTH 
HEADER = 
BINARY 3 


ASCII 

CODES 
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Similarly, reading numeric data from an ASCII file can be a complex and relatively slow 
operation. The numeric characters in an item must be entered and evaluated individually by the 
system’s “number builder” routine, which derives the number’s internal representation. (Keep 
in mind that this routine is called automatically when data are entered into a numeric variable.) 
For example, suppose that the following item is stored in an ASCII file: 


0 

10 

A 

B 

C 

= 


1 

2 

3 

X 

Y 


... j 




LENGTH ASCII 

HEADER = CODES 

BINARY 10 


Although it may seem obvious that this is not a numeric data item, the system has no way of 
knowing this since there is no type-field stored with the item. Therefore, if you attempt to enter 
this item into a numeric variable, the system uses the number-builder routine to strip away all 
non-numeric characters and spaces and assign the value 123 to the numeric variable. When 
you add to this the intricacies of real numbers and exponential notation, the situation becomes 
more complex. For more information about how the number builder works, see Chapter 5 of 
BASIC Interfacing Techniques. 

Because ASCII files require so much overhead (for storage of “small” items), and because 
retrieving numeric data from ASCII files is sometimes a complex process, they are not the 
preferred file type. However, as we mentioned before, ASCII files are interchangeable with 
many other HP products. 

In this chapter, we refer to the data representation described above as ASCII-file format. As 
mentioned earlier, you can also store data in BDAT files in ASCII format (by using the FORMAT 
ON attribute). However, be careful not to confuse ASCII-file format with the ASCII data format. 

In general, you should only use ASCII files when you want to transport data between HP Series 
200 computers and other HP machine(s). There may be other instances where you will want to 
use ASCII files, but you should be aware that they cause a noticable performance degradation 
compared to BDAT files. 
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Mass Storage Techniques 

This section presents BASIC programming techniques useful for accessing mass storage devices 
and files. The first section gives a brief introduction to the steps you might take to store data in a 
file. Subsequent sections describe further details of these steps. If you feel that you need 
additional background information while reading this material, refer to the preceding tutorial 
section. 

Initializing a Disc 

Before a disc is used for the first time, it must be initialized. If the disc has already been 
initialized on a LIF-compatible device, and it contains data you wish to retain, then it can be 
used on a Series 200 computer without initialization. However, if a previously initialized disc 
does not have any data on it (or you don’t need the data on it), it might be advantageous to 
re-initialize it on your computer to get maximum performance. The point is this: a disc must be 
properly initialized before your computer can use it, but initializing a disc destroys all the data 
on the disc. 

The following steps show a typical initialization process using an internal disc drive of a Model 226 
or 236 as an example. The procedure for initializing external discs is very similar, but specific details 
will change. For example, an external disc drive will have a different specifier (not INTERNAL), 
may have a different write-protect convention, and will probably take a different length of time to 
initialize. For other examples, look in your operating manual or check the BASIC Language 
Reference under “MASS STORAGE IS” and “INITIALIZE” 

To initialize a 5.25-inch disc on an internal disc drive, follow these steps: 

1. Make sure that the disc does not contain any important data or programs. Many types of 
computers and word processors use similar discs. When a disc is initialized, all the data on 
it is destroyed! 

2. Ensure that the disc is not “write protected”. The disc envelope has a small notch on one 
side. When this notch is open, the computer is allowed to write on the disc. If this notch is 
covered, data may be read from the disc, but recording is not allowed. Trying to initialize 
a write-protected disc results in error number 83. 

3. Be sure the disc is properly inserted in the right-hand disc drive. 

4. Execute INITIALIZE ":INTERNAL". This command tells the computer to erase all data 
from the disc, format it for use in your computer, check the quality of the media, and create 
the directory area. 

An initialize operation takes about three minutes. The CRT displays the system’s progress 
during this operation. When the initialization is complete, the run light turns off and a message 
similar to the following is displayed. 

INITIALIZE: TRACK 32» SIDE 1. SPARED 0 
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During initialization, the disc is checked for bad areas on the tracks. If a bad spot is found, that 
particular track is rejected (or “spared”). If track 0 is bad or more than four tracks are spared, 
the initialize operation fails and error number 66 is issued. Although a disc with less than 5 
rejected tracks can be used, rejected tracks are an indication that the magnetic surface is not in 
very good condition. 

After the initialization has completed successfully, the disc is ready for storing programs and 
data. 


Disc Labels 

After you initialize the disc, you may want to give it a label. The PRINT LABEL statement prints the 
label in the disc directory. Once the label is there, a READ LABEL statement can retrieve it. The 
disc label is included in a CATalog of the disc. 

For example, to give the disc in the INTERNAL disc drive the label VOL1, execute the following: 
PRINT LABEL "POLl" TO INTERNAL" 

To read the label, enter: 

10 READ LABEL Name* FROM INTERNAL" 

Disc labels are useful in many cases. When a program asks the operator to insert a particular disc in 
the disc drive, the program can read the label to insure the correct disc was inserted. 


1000 

Insert: (Insert disc 


1010 

DISP "Insert disc 00L1 in the 

INTERNAL disc drive 

1020 

PAUSE 


1030 

READ LABEL Label$ FROM ":INTERNAL" 

1040 

IF Labe1$<>"U0L1" THEN 


1050 

DISP "You have inserted an 

incorrect disc" 

10G0 

BEEP 


1070 

WAIT 3 


1080 

GOTO Insert 


1090 

END IF 


1100 

RETURN 



If several disc drives are connected to the computer, a program can read the label of each disc to 
find the disc it needs to access. 


2000 

(Read 

the disc labels 


2010 

READ 

LABEL Drive0$ FROM " 

: INTERNAL 1 * 

2020 

READ 

LABEL D riv e1 $ FROM " 

: INTERNAL >4 tl " 

2040 

SELECT 1 


2050 

CASE 

Drive0$= " 0 0 L1 " 


2 0 G 0 


! Access files from 

'* : INTERNAL" 

2070 

CASE 

D ri m e1$="00L1" 


2080 


! Access files from 

":INTERNAL ,4 »1 " 

2090 

CASE 

ELSE 


2100 


! Disc not in drive 


2110 

END SELECT 



: INTERNAL ,1 
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Overview of Mass Storage Access 

Storing data in files requires a few simple steps. The following program segment shows a simplistic 
example of placing several items in a data file. Assume that this program is run on a Model 236. 


390 ! Specify left drive as “system" mass storage* 

400 MASS STORAGE IS INTERNAL>4>1" 

410 ! 

420 ! Create BDAT data file with ten (256-byte) records 
430 ! on the system mas s storage (left drive)* 

440 CREATE BDAT " F i 1 e _ 1 " *10 
450 ! 

4G0 ! Assign (open) an 1/0 path to the file* 

470 ASSIGN @ Pa t h _1 TO "File_l" 

4S0 ! 

490 ! Send an array o f numeric values* 

500 OUTPUT @Path_l5Arrayl(*) 

510 ! 

520 ! Close the I/O path (may be optional)* 

530 ASSIGN @Path_l TO * 


790 ! Open another I/O path to the file* 

800 ASSIGN @F_1 TO "File_l:INTERNAL >4 #1" 

S 10 ! 

820 ! Read data into another array (same size and type)* 

830 ENTER @F_1 5 Array2(*) 

840 ! 

850 ! Close I/O path* 

8G0 ASSIGN @F_1 TO * 

Line 400 specifies the “system mass storage device,” or the “default” device which is to to be 
used whenever a mass storage device is not explicitly specified during subsequent mass storage 
operations. The term mass storage unit specifier (msus) describes the string expression used to 
uniquely identify which device is to be the mass storage. In this case, “:INTERNAL,4,1” is the 
msus. 

In order to store data in mass storage, a data file must be created (or already exist) on the mass 
storage media. In this case, line 440 creates a BDAT file for data storage; the file created 
contains 10 defined records of 256 bytes each. (Defined records and record size are discussed 
later in this chapter.) 

The term “file specifier” describes the string expression used to uniquely identify the file. In this 
example, the file specifier is simply “File_l,” which is the file’s name. If the file is to be created 
(or already exists) on a mass storage device other than the system mass storage, the appropriate 
msus must be appended to the file name. 

Then, in order to store data in (or retrieve data from) the file, you must assign an I/O path name 
to the file. Line 470 shows an example of assigning an I/O path name to the file (also called 
opening an I/O path to the file). Line 500 shows an array of numeric data being sent to the file 
through the I/O path. 
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The I/O path is closed after all data have been sent to the file. In this instance, closing the I/O 
path may have been optional, because another I/O path name is assigned to the file later in the 
program. (All I/O path names are automatically closed by the system at the end of the pro¬ 
gram.) Closing an I/O path to a file updates the file pointers. 

If this array of data is to be retrieved from the file, another ASSIGN statement is executed (line 
800). Notice that a different I/O path name has been used; this is an arbitrary choice of names. 
Opening this I/O path name to the file sets the file pointer to the beginning of the file. (Re¬ 
opening the I/O path name @File_l would have also reset the file pointer.) 

Notice also that the msus is included with the file name. This shows that the mass storage device, 
here the left drive of the Model 236, does not have to be the current system mass storage in order to 
be accessed. The subsequent ENTER statement reads the data into another numeric array (which 
must be of the same data type when a BDAT file is used in this manner). 

As you can see, this is a very simplistic example, in which several assumptions have been made. 
However, it shows the general steps you must take to access files. The rest of this section expands 
on these basic steps. 

Media Specifiers 

Once the mass storage is connected, you need a way of specifying which mass storage device to be 
accessed. This is done with a media specifier. The syntax for a media specifier is illustrated below. 


■O-O-d msus 1-0 



Device type — effectively describes the mass storage device to the system. The system then knows 
the capacity of the device, the directory structure, and other information required to determine the 
access method for the device. Examples are INTERNAL, CS80, and HP82901. 
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The following table shows the valid device types. Most device types require an option BIN for the 
statement to execute. 


BIN Required 

Device Type 

none 

INTERNAL 

MEMORY 

DISC & 

HPIB or FHPIB 

HP 9895 

HP9121X 

HP 9133 

HP 9134 

HP 9135 (5V4 inch uses HPIB not FHPIB) 

HP 913X 

DISC & HPIB 

HP 82901 

HP 82902 

HP 8290X 

CS80& 

HPIB or FHPIB 

CS80 (7908, 7911, 7912, 7914, 9122...) 

HP9885 & GPIO 

HP 9885 

SRM & DCOMM 

REMOTE 

BUBBLE 

BUBBLE 

EPROM 

EPROM 


Note the 98625 Card (which requires the FHFIB BIN) cannot be used with external 5V* inch discs. 


If the device type specified is not valid, the system tests the device to determine its type. There are 
two exceptions to this. 

1. If the device selector is 0 and the device type is invalid, the device type is assumed to be 
MEMORY. 

2. If the device type is valid and the driver BIN for the device is not loaded, the system considers 
the device an invalid device type. 

Device selector — tells the system the select code of the interface connected to the device; if 
the interface is an HP-IB, it also tells the system the device’s primary address. The system then 
knows which interface connects the device to the computer (and the device’s address, if an 
HP-IB is used). 

A device selector can be just an interface select code or a combination of select code and 
primary address. To derive a device selector with a primary address, multiply the interface 
select code by 100 and then add the address. For instance, the device selector 703 would select 
the device with primary address 3 which is connected to the interface at select code 7. Note that 
interface select code 7 is the built-in HP-IB interface; this is the interface you will probably use 
to attach external disc drives. 

The device selector for the internal drive(s) is 4. Note that there is no default device selector for 
external drives; in other words, you could not use just the device type to specify an external 
drive. 
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Unit number — tells the system additional information about the device’s unit-number setting. 
Many devices have hard-wired unit numbers, while others use the unit number to identify different 
portions of one disc. For instance, the unit number of the right drive of a Model 236 is 0, while it is 1 
for the left drive. 

Volume number — a volume is a subdivision of a unit if the device supports volumes. If the volume 
number is not given, the default 0 is used. 

Examples 

The following statements set the system mass storage to an HP 82901 drive at interface select code 
7; the HP 82901 is set to primary address 0 and has a unit number of 1. 

MASS STORAGE IS " : HP82901 >700*1" 
or 

MASS STORAGE IS HP*700,1" 

Executing the following statements catalog the disc in the HP 9121 drive at interface select code 8 
with primary address 2 and unit number 0. 

CAT " :HP9121 *702" 

CAT " :HP *702" 

Again, note that there is no default device selector for external drives; in other words, you cannot 
use just the device type to specify an external drive. 

The following statement creates an ASCII file named “Fred” on the disc in unit 3 of an HP 9134 
drive, connected through interface select code 7; the device has a primary address of 0. 

CREATE ASCII "Fred:HP9134*700>3" 
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Internal Disc Drives 

There are two ways to specify which mass storage device is to be used for an operation. The first 
way is to use a media specifier to specify the system mass storage with the MASS STORAGE IS 
statement. The following statement specifies that the right drive of a Model 236 (the only drive of a 
Model 226) is to be system mass storage. 

MASS STORAGE IS INTERNAL" 

Now whenever you perform a mass storage operation and don’t specify a mass storage device, the 
system will automatically use this mass storage device. This default mass storage remains effective 
until you either execute a new MASS STORAGE IS statement or a SCRATCH A. After a power-up 
or SCRATCH A, the MASS STORAGE IS device is set to the device from which the system was 
booted. 

The second method is to specify a media specifier for the operation. For example, the following 
statement directs the system to catalog the disc media in the left drive (of a Model 236). 

CAT INTERNAL ,4>1" 

Note that, with this second method, using a media specifier overrides the default mass storage for 
the particular operation but does not modify the system mass storage (i.e., the default msus). 

The following statement sets the default mass storage to the left drive of a Model 236. Note that 
“MASS STORAGE IS” can be abbreviated as “MSI.” 

MSI INTERNAL>4>1" 

Executing this statement on a computer other than a Model 236 results in an error, since it has no 
left drive. 

The “4” parameter is the internal drive’s interface select code, and the “1” is the unit number of 
the left drive. It is possible (but redundant) to use the parameters which specify the right-hand drive, 
since the default values also specify the right drive. For example, all of the following statements 
direct the system to catalog the disc in the right drive. 

CAT INTERNAL*4»0" 

CAT INTERNAL*4" 

CAT ":INTERNAL" 

CAT ": »4" 

You can also specify external mass storage devices by using the proper media specifier. The next 
section describes the following topics: external HP drives which are supported by the BASIC 
language of Series 200 Computers and non-disc mass storage devices such as magnetic bubble 
memories. If you aren’t going to use external mass storage, you can skip to the section that 
describes file access. 

External Disc Drives 

HP Series 200 computers support a number of external HP disc drives. The following table shows 
the external drives which can be used. The Total Storage Capacity values given are on a per-media 
basis before the system writes directory information on the media. 



Data Storage and Retrieval 215 


HP Device 

Type of Media 

Total Storage ( 
Bytes 

Capacity: 

Files 

HP 7908 

hard disc (optional tape backup) 

16 576 000 

2 584 

HP 7911 

hard disc (optional tape backup) 

28 114 944 

4 392 

HP 7912 

hard disc (optional tape backup) 

65 601 536 

10 248 

HP 7914 

hard disc (optional tape backup) 

132 120 576 

20 640 

HP9121S 

3.5-inch flexible disc (single-drive) 

270 336 

112 

HP9121D 

3.5-inch flexible disc (dual-drive) 

270 336 

112 

HP 9133 (flexible disc for 

3.5-inch flexible disc 

270 336 

112 

all versions) 




HP 9133 A 

5.25-inch hard disc 

1 152 000 per unit 

464 per unit 

HP 9133A, Option 010 

5.25-inch hard disc 

4 825 088 

752 

HP 9133B 

5.25-inch hard disc 

9 581 920 

1 512 

HP 9133V 

5.25-inch hard disc 

4 825 088 

752 

HP 9133V, Option 004 

5.25-inch hard disc 

1 152 000 per unit 

464 per unit 

HP 9133XV 

5.25-inch hard disc 

14 522 880 

2 264 

HP 9133XV, Option 010 

5.25-inch hard disc 

9 681 920 

1 512 

HP 9134A 

5.25-inch hard disc 

1 152 000 per unit 

464 per unit 

HP 9134A, Option 010 

5.25-inch hard disc 

4 825 088 

752 

HP 9134B 

5.25-inch hard disc 

9 681 920 

1512 

HP 9134XV 

5.25-inch hard disc 

14 522 880 

2 264 

HP 9134XV, Option 010 

5.25-inch hard disc 

9 681 920 

1512 

HP 9135 (flexible disc for 

5.25-inch flexible disc 

270 336 

112 

all versions) 




HP 9135A 

5.25-inch hard disc 

1 152 000 

464 

HP 9135A, Option A 

5.25-inch hard disc 

4 825 088 

752 

HP 9885 

8-inch flexible disc 

483 840 

224 

HP 9895 

8-inch flexible disc (single-sided 
media) 

483 840 

224 

HP 9895 

8-inch flexible disc (double-sided 
media) 

1 152 000 

464 

HP 82901 

5.25-inch flexible disc (dual-drive) 

270 336 

112 

HP 82902 

5.25-inch flexible disc (single-drive) 

270 336 

112 


You can have nearly any number and any combination of these drives connected to your com¬ 
puter; the only restriction is imposed by the number of and the limitations of the interface(s) used to 
connect the drives to the computer. 


The next sections summarize configuring and accessing external devices currently available. The 
following table summarizes pertinent information regarding the available drives. 

All of the entries in the table may not make complete sense to you at this time; however, once you 
connect your drive, you will be able to better understand the data and use the information as a 
handy quick reference. 
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HP Device 

Device 

Type 

Interface 

Required 

Factory ! 
Address 

Settings: 
Unit No. 

Default 

Interleave 

HP 7908 (h) 

C S 8 0 

HP-IB or fast HP-IB 

0 

0 

i 

HP 7908 (t) 

C S 8 0 

HP-IB or fast HP-IB 

0 

1 

— 

HP 7911 (h) 

C S 8 0 

HP-IB or fast HP-IB 

0 

0 

i 

HP 7911 (t) 

CS80 

HP-IB or fast HP-IB 

0 

1 

— 

HP 7912 (h) 

C S 8 0 

HP-IB or fast HP-IB 

0 

0 

i 

HP 7912 (t) 

C S 8 0 

HP-IB or fast HP-IB 

0 

1 

— 

HP 7914 (h) 

C S 8 0 

HP-IB or fast HP-IB 

0 

0 

i 

HP9121S (t) 

HP9121 

HP-IB or fast HP-IB 

0 

0 

2 

HP 9121D (1) 

HP9121 

HP-IB or fast HP-IB 

0 

0 

2 

HP 9121D (r) 

HP9121 

HP-IB or fast HP-IB 

0 

1 

4 

HP 9133 (f, all versions) 

HP913X 

HP-IB or fast HP-IB 

2 

0 

2 

HP 9133A (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 thru 3 

9 

HP 9133A, Opt. 010 (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 

9 

HP 9133B (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 

9 

HP 9133V (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 

9 

HP 9133V, Opt. 004 (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 thru 3 

9 

HP 9133 XV (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 

9 

HP 9133XV, Opt. 010 (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 

0 

HP 9134A 

HP913X 

HP-IB or fast HP-IB 

0 

0 thru 3 

9 

HP 9134A, Opt. 010 (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 

9 

HP 9134B 

HP913X 

HP-IB or fast HP-IB 

0 

0 

_ 

HP 9134XV 

HP913X 

HP-IB or fast HP-IB 

0 

0 

— 

HP 9134XV, Opt. 010 (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 

— 

HP 9135 (f, all versions) 

HP913X 

HP-IB 

2 

0 

4 

HP 9135A (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 thru 3 

9 

HP 9135A, Opt. 010 (h) 

HP913X 

HP-IB or fast HP-IB 

0 

0 

9 

HP 9885M 

HP9885 

GPIO & DMA 

_ 

0 

1 

HP 9885S 

HP9885S 

GPIO & DMA 

— 

1 

1 

HP 9895M (1) 

HP9895 

HP-IB or fast HP-IB 

0 

0 

3 

HP 9895M (r) 

HP9895 

HP-IB or fast HP-IB 

0 

1 

3 

HP 9895S (1) 

HP9895 

HP-IB or fast HP-IB 

0 

2 

3 

HP 9895S (r) 

HP9895 

HP-IB or fast HP-IB 

0 

3 

3 

HP 82901M (1) 

HP82901 

HP-IB 

0 

0 

4 

HP 82901M (r) 

HP82901 

HP-IB 

0 

1 

4 

HP 82901S (1) 

HP82901 

HP-IB 

0 

2 

4 

HP 82901S (r) 

HP82901 

HP-IB 

0 

3 

4 

HP 82902M 

HP82902 

HP-IB 

0 

0 

4 

HP 82902S 

HP82902 

HP-IB 

0 

2 

4 


(h) indicates hard-disc drive 
(f) indicates flexible disc drive 
(t) indicates tape drive 


(1) indicates right drive (of dual-drive machine) 
(r) indicates left drive (of dual-drive machine) 
— indicates “not applicable” 
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Now let’s take a closer look at each of these drives and briefly summarize the configuration 
considerations. 

HP 7908, 7911, 7912, and 7914 Disc/Tape Drives 

These machines all have a hard disc drive and tape (backup) drive; the differences between model 
numbers are primarily disc (and tape) capacities. Tape drives may be optionally deleted when 
ordering the machine. Using these drives requires CS80 and HPIB or FHPIB. 

If the disc and tape drive have only one controller, both are located at the same primary address; 
this address has a random factory setting in the range 0 through 7. If disc and tape each have their 
own controller, each also has its own address setting. The address switch setting(s) are located on 
the rear panel below the HP-IB connector; see the installation manual for the switch definitions. 
The unit number of the disc is 0, and the unit number of the tape is 1. 

To specify any of these drives, use the device type CS80. For instance, to specify the disc at 
interface select code 7 with primary address 0, use : CS80 >700; to specify the tape on the same 
machine, use : C S 8 0 > 7 0 0 > 1. 

The default interleave factor for all CS80 discs is 1, which is optimal for an HP 7908 while using 
DMA. For the HP 7912, an interleave of 3 is optimal (while using DMA). Time-critical operations 
may perform better with an interleave of 3, 7, or 12. 

Note that you should not use the COPY statement to do media backup between the disc drive and 
the tape drive. The utility program “TAPEBACKUP” has been provided with the BASIC Utilities 
Library for this purpose. 

HP 9121S and 9121D Drives 

The HP 9121S is a single-drive machine, and the HP 9121D is a dual-drive machine. Both use 
3.5-inch flexible discs. Using these drives requires DISC and HPIB or FHPIB. 

The factory default setting of the primary address is 0. The address switches are located on the rear 
panel; see the installation manual for switch definitions. With the HP 9121D, the left drive is set to 
unit 0, and the right drive is set to unit 1. 

To specify these drives, use any of the device types HP9121, HP8290X, or HP913X. To specify the 
right drive on an HP 9121D at interface select code 7 with primary address 0, use 
: H P9 1 2 1 > 700 > 1. To specify the drive of an HP 9121S at select code 8 with primary address 2, 
use : HP9121 >802. 

The default interleave factor is 2 for HP 9121 drives. 

HP 9133, 9134, and 9135 Drives 

All of these drives feature a 5.25-inch hard-disc drive. The HP 9133 contains an additional 3.5-inch 
flexible disc drive, which uses media compatible with HP 9121 drives. The HP 9135 contains an 
additional 5.25-inch flexible disc drive, which uses media compatible with internal and HP 8290X 
drives. Using these drives requires DISC and HPIB for flexible disc drives or FHPIB for other 
devices. 
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The drives are available in the following sizes and configurations: 


Option 

Size 

Volumes 

A 

4 825 088 

4 

A, Option 010 

4 825 088 

1 

B 

9 681 920 

1 

V 

4 825 058 

1 

V, Option 004 

4 825 088 

4 

XV 

14 522 880 

1 

XV Option 010 

9 681 920 

1 


The available combinations are: 


HP 9133 

HP 9134 

HP 9135 

Options 

Yes 

Yes 

Yes 

A 

Yes 

Yes 

Yes 

A, Option 010 

Yes 

Yes 

No 

B 

Yes 

No 

No 

V 

Yes 

No 

No 

V, Option 004 

Yes 

Yes 

No 

XV 

Yes 

Yes 

No 

XV, Option 010 


The factory default setting of the primary address switches for the hard disc on all three of these 
devices is 0; for the flexible discs (HP 9133 and HP 9135), the default address is 2. The switches 
are located on the rear panel; see the installation manual for switch definitions. 

The default interleave factor for these drives is 2 (for flexible discs) and 9 (for hard discs). The 
interleave of the hard discs is 9 and cannot be changed. 

HP 9885 Drives 

The HP 9885 is a single-drive, single-sided, 8-inch, flexible disc drive. Unlike the other disc drives, 
using this device requires a GPIO Interface (HP 98622) and a DMA Interface (HP 98620). The 
factory default setting of the GPIO Interface’ select code is 12; the range of allowable select codes is 
8 through 31, as long as no other interface is set to the same select code. The DMA Interface has no 
select code setting. Using this drive requires HP9885 and GPIO. 

The “INT LVL” switches are irrelevant when using the HP 9885. All “Option Select” switches 
(PCTL, PFLG, PSTS, HSHK, DIN, and DOUT) must be set to the “1” position (open). The 
“Data-In Clock Source” switches must be set as follows: 



Switch Name 

Required Setting 


READ 

1 (open) 

LOWER 

BSY 

0 (closed) 


RDY 

1 (open) 


READ 

1 (open) 

UPPER 

BSY 

0 (closed) 


RDY 

1(open) 
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There is no primary address setting for the HP 9885 drives, since these drives are connected to the 
computer through a GPIO Interface. The factory default settings for unit numbers depend on 
whether or not the drive is a master or slave drive; HP 9885M drives are masters, and HP 9885S 
drives are slaves. Master drives have a default unit number of 0, while the slaves have defaults of 1. 
Each master can control up to three slaves. The unit-number switch is a rotary switch located on the 
rear panel. 

To specify an HP 9885 at interface select code 12 and with unit number 0, use :HP9885 > 1 2; to 
specify a drive at the same select code but with unit number 1, use :HP9885>12>1. 

HP 9895 Drives 

The HP 9895 disc drives are dual-drive machines which can use either single-sided or double¬ 
sided, 8-inch, flexible-disc media. The single-sided media are compatible with HP 9885 drive. 
Using these drives requires DISC and HPIB or FHPIB. 

The primary address switch is located behind the removable front panel; the factory default address 
setting is 0. The unit number of the left drive is 0; for the right drive, it is 1. 

To specify an HP 9895 drive, use the H P9895 device type. For instance, to specify the right drive of 
an HP 9895 located at interface select code 7 with primary address 0, use : HP9895 >700 > 1; to 
specify the left drive of the same machine, use :HP9895 >700. 

The default interleave factor for HP 9895 discs is 3. 

HP 82901 and HP 82902 Drives 

The HP 82901 drives are dual-drive machines, while the HP 82902 drives are single-drive 
machines. The M suffix (of the part number) denotes that the machine is a master drive; master 
drives can control one slave drive (either an HP 82901 or HP 82902 which has an S suffix). The 
media used with both of these 5.25-inch flexible disc drives are compatible with the internal and HP 
9135 flexible disc drives. Using these drives requires DISC and HPIB 

The primary address switches are located on the master drive’s rear panel under the HP-IB 
connector. The factory default primary address setting is 0; see the installation manual for switch 
definitions. On the HP 82901M, the left drive is unit 0, and the right drive is unit 1; the single drive 
of the HP 82902M is unit 0. On an HP 82901S, the left drive is unit 2, and the right drive is unit 3; 
the single drive of an HP 82902S is unit 2. 

To access these drives, use any of the HP8290X device types. For instance, to specify the left drive 
of an HP 82901 at select code 7 with primary address 0, use HP8290 1 >700; to specify the right 
drive of the same machine, you could use HP829OX >700 > 1. 
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Non-Disc Mass Storage 

Although mass storage is traditionally implemented using a magnetic surface such as a disc or drum, 
the protocols of file management can be applied to any device which stores data. Here is a 
summary. 

• EPROM (Erasable, Programmable Read-Only Memory) cards. Although EPROMs store user- 
supplied data, they are much harder to write than to read. This, combined with their rugged¬ 
ness and non-volatile storage, makes them well suited to read-only applications in environ¬ 
ments too harsh for a disc. Because of their specialized nature, EPROMs are not discussed in 
this chapter on generalized mass storage. They are covered in their own chapter of BASIC 
Interfacing Techniques. 

• Magnetic Bubble Memory cards. Like EPROMs, these devices provide non-volatile storage 
that is more rugged than a disc. Unlike EPROMs, bubble memory can be written to just as 
easily as it can be read. 

• RAM Memory Volumes. Areas of the computer’s RAM can be treated as though they were 
mass storage devices. Obviously, a RAM volume is volatile. However, they can be accessed 
faster than any other mass storage device. Some special tasks can benefit from this increased 
speed for intermediate operations and then copy the RAM volume to a non-volatile volume at 
the end of the job. 

The next two sections describe some of the programming techniques needed to access bubble 
memory and RAM volumes. 

Bubble memory 

The Bubble Memory Card is very similar to an interface card. It has interface select code switches 
and installs in an accessory slot. The Installation Note for this card shows how to set the switches. 
Note that hardware interrupt level of 6 is recommended. The BUBBLE BIN is required to use this 
card. 

The follow example show typical mass storage unit specifiers for a bubble memory card set to 
interface select code 30. 

MASS STORAGE IS BUBBLE>30" 

ASSIGN @Fi 1e TO " data 1:BUBBLE>30" 

A bubble memory card always has only one unit (unit 0). This could be specified in the media 
specifier, such as : BUBBLE >28 >0. However, zero is the default unit number in a media speci¬ 
fier, so there is really no point in specifying it. 

All mass storage operations work with the bubble memory card. Just use the card’s interface 
select code in the BUBBLE media specifier. There are very rare instances when hardware 
conflicts might occur during a bubble memory access. These pertain to hardware interrupt 
levels, which are described in BASIC Interfacing Techniques. Essentially, if an interrupt (at the 
same or higher priority) occurs during a bubble memory access, BASIC might not be able to 
service the bubble memory card quickly enough. If this happens, error 314 is reported. The 
cure is to lower the hardware interrupt level of the cards in conflict with the bubble card or 
restructure the program so that the conflicting operations (e.g. TRANSFER) do not occur at the 
same time. 
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When the bubble memory device was first initialized at the factory, any bad loops (memory 
locations) were logged and this information, called the Boot Loop, was stored in the bubble 
memory device itself. If you obtain repeated “read” errors or “buffer overflow” errors from the 
bubble memory card, try to re-initialize the volume. If the initialization fails, it is likely the Boot 
Loop information has been lost and the card should be returned to re-establish the Boot Loop. 

RAM Volumes 

Areas of the computers RAM may be treated as mass storage devices. These “memory volumes” or 
“RAM volumes” are volatile (all information is lost when the power goes off), but high speed. A 
typical use for RAM volumes is to copy a disc volume into memory, perform all necessary man¬ 
ipulations using the RAM volume, then copy the new information back to disc. Obviously, there are 
only certain applications which would benefit from this technique. 

All mass storage operations work with RAM volumes. After they are created (described next), RAM 
volumes are accessed by using their unit number in a MEMORY media specifier. The following 
examples show typical mass storage unit specifiers for a RAM volume with unit number 7. 

MASS STORAGE IS MEMORY>0*7" 

ASSIGN @Ram TO "TEMP:MEMORY ,0>7" 

RAM volumes are created by the INITIALIZE statement. A special form of this statement is used, 
with a unit size parameter is the position normally occupied by the interleave factor. The device 
type is always MEMORY, and the device selector is always 0. Unit numbers 0 thru 31 may be used. 
Here are some examples. 

INITIALIZE ":MEMORY .0,1 " >220 

This creates a RAM volume that is 220 sectors long and is given unit number 1. Note that the unit 
size parameter is in 256-byte sectors, just like LIF file sizes. 

If the unit size parameter is omitted, the result is a RAM volume that is the same size as a 5.25-inch 
or 3.5-inch disc. This a 1056 sectors, or 270 336 bytes. Although the default size RAM volume 
provides only 80 directory entries while the discs may contain up to 112 directory entries, if a disc is 
copied into the RAM volume, the entire directory will be copied. 

The unit size of a RAM volume must be at least 4 sectors and can be as large as available memory 
permits. Two sectors are taken for system use, and about 1 sector of directory is created for each 
100 sectors of unit size. The following table shows examples of size data for RAM volumes. 


Specified Unit 
Size (sectors) 

Total Overhead 
(sectors) 

Maximum Number of 
Files in Directory 

4 

3 

8 

200 

3 

8 

201 

4 

16 

300 

4 

16 

512 

7 

40 

1000 

11 

72 

1056 

12 

80 

2000 

21 

152 

2048 

22 

160 
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With BASIC 3.0 RAM volumes can be initialized while a program is running. 

No RAM volumes exist at power-up or after a SCRATCH A. It is recommended that all BIN 
programs be loaded before RAM volumes are initialized. If a BIN program is loaded after a RAM 
volume is initialized, the memory used for the RAM volume cannot be recovered until the computer 
is turned off and back on again. 

A RAM volume can be reinitialized to the same or different size. If the size is different, memory 
space may be lost until the next SCRATCH A. 

Accessing Files 

Before you can access a data file, you must assign an I/O path name to the file. Assigning an I/O 
path name to the file sets up a table in computer memory that contains various information 
describing the file, such as its type, which mass storage device it is stored on, and its location on the 
media. The I/O path name is then used in I/O statements (OUTPUT, ENTER, and TRANSFER) 
which move the data to and from the file. I/O path names are also used to transfer data to and from 
devices. Chapters 4, 5, 10, and 11 of BASIC Interfacing Techniques explain data transfers with 
devices and provide several relevant insights into data representations. However, in this chapter we 
deal only with I/O paths to files. 

Every I/O path to a file maintains the following information: 

Validity Flag — Tells whether the path is currently opened (assigned) or closed (not assigned). 
Type of Resource — Holds the file type (ASCII or BDAT). 

Device Selector — Stores the device selector of the drive. (I/O paths can also be associated with 
devices and buffers. See BASIC Interfacing Techniques for further details.) 

Attributes — Such as FORMAT OFF and FORMAT ON. 

File Pointer — There is a file pointer that points to the place in the file where the next data item will 
be read or written. The file pointer is updated whenever the file is accessed. 

End-Of-File Pointer — An I/O path has an EOF pointer that points to the byte that follows the last 
byte of the file. 

Opening an I/O Path 

I/O path names are similar to other variable names, except that I/O path names are preceded by the 
character. When an I/O path name is used in a statement, the system looks up the contents of 
the I/O path name and uses them as required by the situation. 
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To open an I/O path to a file (to set the validity flag to Open), assign the I/O path name to a file 
specifier by using an ASSIGN statement. For example, executing the following statement: 

ASSIGN @Path1 TO "Example" 

assigns an I/O path name called @Pathl to the file “Example”. The file that you open must already 
exist and must be a data file. If the file does not satisfy one of these requirements, the system will 
return an error. If you do not use an msus in the file specifier, the system will look for the file on the 
current MASS STORAGE IS device. If you want to access a different device, use the msus syntax 
described earlier. For instance, the statement: 

ASSIGN @Path2 TO "Example:HP9895.707" 

opens an I/O path to the file “Example” on an HP 9895 disc drive, interface select code 7 and 
primary address 7. You must include the protect code if the file has one. 

ASSIGNing an I/O path name to a file has the following effect on the I/O path table: 

• If the I/O path is currently open, the system closes the I/O path and then re-opens it. If the I/O 
path is not currently open, it is opened. In both cases, the system sets the validity flag to Open. 

• The file type (ASCII or BDAT) and its msus are recorded. 

• The specified attributes are assigned to the I/O path name. If an attribute is not specified, the 
appropriate default attribute is assigned. 

• The file pointer is positioned to the beginning of the file. 

• If the path name is associated with a BDAT file, the EOF pointer from the system sector is 
copied to the I/O path table. 

Once an I/O path has been opened to a file, you always use the path name to access the file. An I/O 
path name is only valid in the context in which it is opened, unless you pass it as a parameter or put 
it in the COM area. To place a path name in the COM area, simply specify the path name in a COM 
statement before you ASSIGN it. For instance the two statements below would declare an I/O path 
name in an unnamed COM area and then open it: 

100 COM @Path3 

110 A98IGN @Path3 TO "Filel" 

Assigning Attributes 

When you open an I/O path, certain attributes are assigned to it which define the way data is to be 
read and written. There are two attributes which control how data items are represented: FORMAT 
ON and FORMAT OFF. With FORMAT ON, ASCII data representations are used; with FORMAT 
OFF, the system’s internal data representations are used. Additional attributes are available, which 
provide control of such functions as parity generation and checking, converting characters, and 
changing end-of-line (EOL) sequences. See the BASIC Language Reference or Chapter 10 of 
BASIC Interfacing Techniques for further details. 

As mentioned in the tutorial section, BDAT files can use either data representation; however, ASCII 
files only permit ASCII-file format. Therefore, if you specify FORMAT OFF for an I/O path to an 
ASCII file, the system ignores it. The following two examples of ASSIGN statements specify a 
FORMAT attribute. 

A99IGN @Path1 TO "Fi1e1"5FORMAT OFF 



224 Data Storage and Retrieval 


If “Filel” is a BDAT file, the FORMAT OFF attribute specifies that the internal data formats are to 
be used when sending and receiving data through the I/O path. If the file is of type ASCII, the 
attribute will be ignored. Note that FORMAT OFF is the default FORMAT attribute for BDAT files. 

Executing the following statement directs the system to use the ASCII data representation (if 
possible) when sending and receiving data through the I/O path. 

ASSIGN @Path2 TO "Fi 1 e2" iFORMAT ON 

If “File2” is a BDAT file, data will be written using ASCII format, and data read from it will be 
interpreted as being in ASCII format. For an ASCII file, this attribute is redundant since ASCII-file 
format is the only data representation allowed anyway. 

If you want to change the attribute of an I/O path, you can do so by specifying the I/O path name 
and attribute in an ASSIGN statement while excluding the file specifier. For instance, if you wanted 
to change the attribute of @Path2 to FORMAT OFF, you could execute: 

ASSIGN @Pat h2 5FORMAT OFF 
Alternatively, you could re-enter the entire statement: 

ASSIGN @Path2 TO "Fi 1e2“ !FORMAT OFF 

These two statements, however, are not identical. The first one only changes the FORMAT attri¬ 
bute. The second statement resets the entire I/O path table (e.g., resets the file pointer to the 
beginning of the file). 

It is important to note that once a file is written, changing the FORMAT attribute of an I/O path to 
the file should only be attempted by experienced programmers. In general, data should always be 
read in the same manner as it was written. For instance, data written to a BDAT file with FORMAT 
OFF should also be read with FORMAT OFF, and vice versa. In addition, the same data types 
should be used to write the file as to read the file. For instance, if data items were written as 
INTEGERS, they should also be read as INTEGERS. 

In theory, there is no limit to the number of I/O paths you can ASSIGN to the same file. Each I/O 
path, however, has its own file pointer and EOF pointer, so that in practice it can become ex¬ 
ceedingly difficult to keep track of where you are in a file if you use more than one I/O path. We 
recommend that you use only one I/O path for each file. 

Closing I/O Paths 

I/O path names not in the COM area are closed whenever the system moves into a stopped state 
(e.g., STOP, END, SCRATCH, EDIT, etc.). I/O path names local to a context are closed when 
control is returned to the calling context. Re-ASSIGNing an I/O path name will also cancel its 
previous association. 

You can also explicitly cancel an I/O path by ASSIGNing the path name to an * (asterisk). For 
instance, the statement: 

ASSIGN @Path2 TO * 

closes @Path2 (sets the validity flag to Closed). @Path2 cannot be used again until it is Re- 
ASSIGNed. You can Re-ASSIGN a path name to the same file or to a different file. 
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Reading and Writing BDAT Files 

There are many alternatives for storing and retrieving data when using BDAT files. You can 
choose internal ASCII or user-defined formats and serial or random access. The following 
descriptions of OUTPUTing and ENTERing data apply only to BDAT files using FORMAT OFF. 
For more information about OUTPUT, ENTER, IMAGE specifiers, and additional attributes, 
see the BASIC Interfacing Techniques manual. 

System Sector 

On the disc, every BDAT file is preceded by a system sector that contains an End-Of-File 
pointer and the number of defined records in the file. All data is placed in succeeding sectors. 
You cannot directly access the system sector. However, as you shall see later, it is possible to 
indirectly change the value of an EOF pointer. 



0 1 

2 3 

EC 

POIN 

NUMBER 
)F OF 

ITER DEFINED 
|RECORDS 




• • • s 



SYSTEM SECTOR DATA 


Defined Records 

To access a BDAT file randomly, you specify a particular defined record. Records are the 
smallest units in a file directly addressable by a random OUTPUT or ENTER. They can be 
anywhere from 1 through 65 534 bytes long. Both the length of the file and the length of the 
defined records in it are specified when you create the file. For example, the statement: 

CREATE BDAT "Ex amp1e" , 7 ,128 

would create a file called “Example” with 7 defined records, each record being 128 bytes long. 
If you don’t specify a record length in the CREATE BDAT statement, the system will set each 
record to the default length of 256 bytes. 

Both the record length and the number of records are rounded to the nearest integer. Further, 
the record length is rounded up to the nearest even integer. For example, the statement: 

CREATE BDAT "Odd" >3.5 ,28.7 

would create a file with 4 records, each 30 bytes long. On the other hand, the statement: 

CREATE BDAT"Odder">3.49>28.3 
would create a file with three records, each 28 bytes long. 

Once a file is created, you cannot change its length or the length of its records. You must 
therefore calculate the record size and file size required before you create a file. 
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Choosing A Record Length 

The most important consideration in selecting of a proper record length is the type of data being 
stored and the way you want to retrieve it. Suppose, for instance, that you want to store 100 
real numbers in a file, and be able to access each number individually. Since each REAL 
number uses 8 bytes, the data itself will take up 800 bytes of storage. 


SYSTEM SECTOR 






800 BYTES OF DATA 


The question is how to divide this data into records. If you define the record length to be 8 
bytes, then each REAL number will fill a record. To access the 15th number, you would specify 
the 15th record. If the data is organized so that you are always accessing two data items at a 
time, you would want to set the record length to 16 bytes. 

The worst thing you can do with data of this type is to define a record length that is not evenly 
divisible by eight. If, for example, you set the record length to four, you would only be able to 
randomly access half of each real number at a time. In fact, the system will return an End-Of- 
Record condition if you try to randomly read data into REAL variables from records that are less 
than 8 bytes long. 

So far, we have been talking about a file that contains only REAL numbers. For files that 
contain only INTEGERS, you would want to define the record length to be a multiple of two. To 
access each INTEGER individually, you would use a record length of two; to access two 
INTEGERS at a time, you would use a record length of four, and so on. 

Files that contain string data present a slightly more difficult situation since strings can be of 
variable length. If you have three strings in a row that are 5, 12, and 18 bytes long, respectively, 
there is no record length less than 22 that will permit you to randomly access each string. If you 
select a record length of 10, for instance, you will be able to randomly access the first string but 
not the second and third. 

If you want to access strings randomly, therefore, you should make your records long enough 
to hold the largest string. Once you’ve done this, there are two ways to write string data to a 
BDAT file. The first, and easiest, is to output each string in random mode. In other words, select 
a record length that will hold the longest string and then write each string into its own record. 
Suppose, for example, that you wanted to OUTPUT the following 5 names into a BDAT file and 
be able to access each one individually by specifying a record number. 

John Smith 
Steve Anderson 
Mary Martin 
Bob Jones 
Beth Robinson 
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The longest name, “Steve Anderson”, is 14 characters. To store it in a BDAT file would require 
18 bytes (four bytes for the length header). So you could create a file with record length of 18 
and then OUTPUT each item into a different record: 


100 

CREATE 

BDAT "Names" >5 >18 

! Create a file* 

110 

ASSIGN 

@F i 1 e TO 

"Names" 

! Open an 1/0 

path 

120 

OUTPUT 

@F i 1 e ♦ 1 5 

"John Smith" 

! Write names 

t 0 

130 

OUTPUT 

©File >25 

"Steve Anderson" 

! successive 

records 

140 

OUTPUT 

©File>35 

"Mary Martin" 

! in file 


150 

OUTPUT 

©File>4 5 

"Bob Jones" 



ISO 

OUTPUT 

@F i 1 e >5 5 

"Beth Robinson" 




On the disc, the file “Names” would look like the figure below. The four-byte length headers 
show the decimal value of the bytes in the header. The data are shown as ASCII characters. 
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1 = length header 

x = whatever data previously resided in that space 
@ = pad character 


The unused portions of each record contain whatever data previously occupied that physical 
space on the disc. 


The other method for writing strings to a BDAT file is to pad each entry so that they are all of 
uniform length. While this method involves more programming, it allows you to pad the unused 
portions of each record with whatever characters you choose. It also permits you to read and 
write the data serially as well as randomly. The program below shows how you might enter the 
five names into a file by padding each name with spaces. 


100 CREATE BDAT "N 

HO ASSIGN @Pathl 

120 FOR En t ry = 1 TO 

130 LINPUT Name 

140 OUTPUT @Pat 

150 NEXT Entry 


a m e s " > 5 > 1 8 

! Cre 

TO "Names" 

! Ope 

5 


$[1514] 

! Get 

hi 5Name$ 

! W r i 


ate file* 

n 1/0 path to file* 

names from K e y b o a rd 
te name to file 


In this program, we input each name from the keyboard and so that it is padded with spaces to a 
length of 14 bytes. With the length header, each entry is 18 bytes, or one record. In line 140, we 
write the name serially to the file. Since every data item is 18 bytes, there is no need to write 
randomly, although we could if we wanted to. Since the LINPUT statement is limited to 14 
bytes, any names that are longer than 14 characters are automatically truncated. 

If we had used the second program to enter the names, file “Names” would look like the figure 
below: 
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EOF Pointers 

There are two types of End-Of-File pointers. One is maintained internally in the I/O path table 
and the other resides in the system sector. The two pointers are always updated at the same 
time so that they always agree with one another. (This may not be true if you use more than one 
I/O path to OUTPUT data to one file.) The two pointers are updated when either of the two 
conditions below occur. 

• If, after an OUTPUT statement has been executed, the file pointer value is greater than the 
EOF pointers, the EOF pointers are moved to the file pointer position. 

• If an OUTPUT statement contains the “END” secondary word, the EOF pointers are 
moved to the file pointer position regardless of their current values. 

The function of EOF pointers is to mark the logical end of a data file. Every file also has a 
physical EOF — the last byte reserved for the file when you create it. The EOF pointers cannot 
point beyond the physical EOF. The EOF pointer marks the point at which no more data can be 
read. Also, you cannot randomly write data more than one record past the EOF position. 

If you have a 100-record file, and the EOF pointers point to the 50th record, records 50 through 
100 cannot be read. If you attempt to read data beyond an EOF, an EOF condition occurs. EOF 
conditions can be trapped with an ON END statement. If you do not trap it, an EOF condition 
will cause Error 59. Attempting to read or write beyond the physical EOF will also result in an 
EOF condition. EOF conditions are described in more detail later in this chapter. 

Moving EOF Pointers 

When you first create a file, the EOF pointer in the system sector points to the first byte in the 
file. When you ASSIGN an I/O path to a file, the pointer in the system sector is copied to the I/O 
path table. As you OUTPUT data items to the file, both EOF pointers are changed so that they 
point to the next byte. This is also where the file pointer is positioned. 

If you overwrite a file, however, the EOF pointers will not necessarily agree with the file pointer. 
For example, suppose you write 100 bytes to a file, and then re-ASSIGN the I/O path. By 
re-ASSIGNing, you move the file pointer back to the first byte in the file. The EOF markers, 
though, still point to the 101st byte. They will not be changed until the file pointer value is 
greater than 101, or until you specify an “END” in an OUTPUT statement. 

The secondary word “END” is used to move the EOF pointers backwards. It forces the EOF 
pointers to be re-positioned to the file pointer byte, even if the new position is “earlier” in the 
file than their current position. In effect, this “shrinks” the file, causing data that lies past the 
new EOF position to become inaccessible. 
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Writing Data 

Data is always written to a file with an OUTPUT statement via an I/O path. You can OUTPUT 
numeric and string variables, numeric and string expressions, and arrays. When you OUTPUT 
data with the FORMAT OFF, data items are written to the file in internal format (described 
earlier). 

There is no limit to the number of data items you can write in a single OUTPUT statement, except 
that program statements are limited to two CRT lines. Also, if you try to OUTPUT more data than 
the file can hold, or the record can hold (if you are using random access), the system will return an 
EOF or EOR condition. If an EOF or EOR condition occurs, the file retains any data output ahead 
of the end condition. 

There is also no restriction on mixing different types of data in a single OUTPUT statement. The 
system decides which data type each item is before it writes the item to the disc. Any item 
enclosed in quotes is a string. Numeric variables and expressions are OUTPUT according to 
their type (8 bytes for REALs and 2 bytes for INTEGERS). Arrays are written to the file in row 
major order (rightmost subscript varies quickest). 

Each data item in an OUT PUT statement should be separated by either a comma or semi-colon 
(there is no operational difference between the two separators with FORMAT OFF). Punctua¬ 
tion at the end of an OUTPUT statement is ignored with FORMAT OFF. 


Serial OUTPUT 

Data is written serially to BDAT files whenever you do not specify a record number in an 
OUTPUT statement. When data is written serially, each data item is stored immediately after 
the previous item without any type of separator. Sector and record boundaries are ignored. 
Data items are written to the file one by one, starting at the current position of the file pointer. 
As each item is written, the file pointer is moved to the next byte. After all of the data items have 
been OUTPUT, the file pointer points to the first byte following the last byte just written. 

There are a number of circumstances where it is faster and easier to use serial access instead of 
random access. The most obvious case is when you want to access the entire file at once. If, for 
example, you have a list of data items that you want to store in a file and you know that you will 
never want to read any of the items individually, you should write the data serially. The fastest 
way to write data serially is to place the data in an array and then OUTPUT the entire array at 
once. 

Another situation where you might want to use serial access is if the file is so small that it can fit 
entirely into internal memory at once. In this case, even if you want to change individual items, 
it might be easier to treat the entire file as one or more arrays, manipulate as desired, and then 
write the entire array(s) back to the file. 
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The examples below illustrate how data is stored serially in a file. The statement: 

OUTPUT @Path 1 5 "First" >24 52.B» 
would result in the following storage format: 



0 

0 

0 

5 

F 

i 

r 

s 

t 

(pad) 












LENGTH 

ASCII 

INTEGER 24 

REAL 2.6 

HEADER =5 

CODES 




Note that quotation marks around a string are not written to the file. To write quote marks to a 
file, enter two quote marks for every one you want to OUTPUT. Note also that separators are 
not written to the file. To write a comma or semi-colon to a file, you must enclose it in quotes. 
For instance, the statement: 

OUTPUT SPathli .QUO""TES" >"Next" 

would be stored: 
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LENGTH ASCII LENGTH ASCII 

HEADER =8 CODES HEADER =4 CODES 


The following sequence of serial OUTPUT statements show how data is written to a BDAT file 
and how the file pointer and EOF pointers are updated. 

CREATE BDAT "Example" >4 >128 


I/O PATH TABLE 


FILE POINTER 


EOF POINTER 



SYSTEM 

SECTOR 


Creates a BDAT file with four 128-byte records. The EOF pointer in the system sector points to 
the first byte in the file. 
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ASSIGN OPathi TO "Example" 


I/O PATH TABLE 



SECTOR 


Opens an I/O path to “Example”. The EOF marker in the system sector is copied to the I/O 
path table. The file pointer is positioned to the beginning of the file. 

OUTPUT @Path15"TEN CHARS." 


I/O PATH TABLE 



SYSTEM LENGTH ASCII 

SECTOR HEADER =10 CODES 


Fourteen bytes are written to the file. The EOF pointers are moved to the 15th byte. The file 
pointer also points to the 15th byte. 
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OUTPUT iPathl5 12,5 ,END 


I/O PATH TABLE 



SYSTEM REAL 12.5 

SECTOR 


Eight more bytes are written to the file. The file pointer now points to the 23rd byte. Both the 
EOF in the I/O path table and the EOF in the system sector are updated to 23. 

OUTPUT iPath1 5 " FOUR" 


I/O PATH TABLE 



SYSTEM REAL 12.5 LENGTH ASCII 

SECTOR HEADER = 4 CODES 


Eight more bytes are written to the file. The file pointer now points to the 31st byte. The EOF 
markers are updated to 31 because 31 is greater than 23, the current EOF value. 
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ASSIGN iPathl TO "Example" 


I/O PATH TABLE 



Re-ASSIGNs the I/O path name. The file pointer is positioned back to the beginning of the file. 
The system sector EOF value is copied to the I/O path table. 

OUTPUT iPathli13»7.BBS»l/3»END 


I/O PATH TABLE 



18 bytes (one INTEGER and two REALs) are OUTPUT, starting at the beginning of the file. The 
original data, therefore, is overwritten. The file pointer points to the 19th byte. The EOF 
markers are also positioned to 19 because the statement contains the “END” secondary word. 
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Random OUTPUT 

Random OUTPUT allows you to write to one record at a time. As with serial OUTPUT, there 
are EOF and file pointers that are updated after every OUTPUT. The EOF pointers follow the 
same rules as in serial access. The file pointer positioning is also the same, except that it is 
moved to the beginning of the specified record before the data is OUTPUT. If you wish to write 
randomly to a newly created file, either use a CONTROL statement to position the EOF in the 
last record, or start at the beginning of the file and write some “dummy” data into every record. 


If you attempt to write more data to a record than the record will hold, the system will return an 
End-Of-Record (EOR) condition. An EOF condition will result if you try to write data more than 
one record past the EOF position. EOR conditions are treated by the system just like EOF 
conditions, except that they return Error 60 instead of 59 if they are not trapped by ON END. 
Data already written to the file before an EOR condition arises will remain intact. The examples 
below illustrate how data is stored randomly. 


CREATE BDAT "Random" 1 10»10 


I/O PATH TABLE 


FILE POINTER 


EOF POINTER 


( EOF 
) POINTER 


SYSTEM 

SECTOR 



SYSTEM 

SECTOR 
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OUTPUT §Path2»15"TOO LONG TO FIT IN RECORD" 


I/O PATH TABLE 



SECTOR HEADER = 25 CODES 

Even though this statement produces an EOR condition, the EOF markers and file pointer are 
still updated. The ON END statement can be used to trap their error. Also, the length header 
represents the length of the string characters sent to the file, since the whole string is not written 
out. 


OUTPUT SPat h2 >2 5 2 


I/O PATH TABLE 



SECTOR 
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OUTPUT @Path2 >3 5"THIRD" 


I/O PATH TABLE 



SYSTEM 2 LENGTH ASCII 

SECTOR HEADER = 5 CODES 


OUTPUT ©Path!>2;a5*78 


I/O PATH TABLE 



SYSTEM REAL 45.78 

SECTOR 
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Reading Data From BDAT Files 

Data is read from files with the ENTER statement. As with OUTPUT, data is passed along an I/O 
path. You can use the same I/O path you used to OUTPUT the data or you can use a different 
I/O path. 

You can have several variables in a single ENTER statement. Each variable must be separated 
by either a comma or semi-colon. It is extremely important to make sure that your variable 
types agree with the data types in the file. If you wrote a REAL number to a file, you should 
ENTER it into a REAL variable; INTEGERS should be entered into INTEGER variables; and 
strings into string variables. The rule to remember is: “Read it the way you wrote it.” 

When reading data into a string variable, it is important to remember that the system will 
interpret the first four bytes after the file pointer as a length header. It will then try to ENTER as 
many characters as the length header indicates. If the string has been padded by the system to 
make its length even, the pad character is not read into the variable. 

After an ENTER statement has been executed, the file pointer is positioned to the next unread 
byte. If the last data item was a padded string, the file pointer is positioned after the pad. If you 
use the same I/O path name to read and write data to a file, the file pointer will be updated after 
every ENTER and OUTPUT statement. If you use different I/O path names, each will have its 
own file pointer which is independent of the other. However, be aware that each also has its 
own EOF pointer and that these pointers may not match, which causes problems. 

Entering data does not affect the EOF pointers. However, you cannot read data at or beyond 
the byte marked by the EOF pointers. If you attempt to read past an EOF marker, the system 
will return an EOF condition. 

In addition to making sure that data types agree, it is also advisable to make sure that access 
modes agree. If you wrote data serially, you should read it serially; and if you wrote it randomly, 
you should read it randomly. There are a few exceptions to this rule which we discuss later. 
However, you should be aware that mixing access modes will often lead to erroneous results 
unless you are aware of the precise mechanics of the file system. 

Serial ENTER 

When you read data serially, the system enters data into variables starting at the current 
position of the file pointer and proceeds byte by byte until all of the variables in the ENTER 
statement have been filled. If there is not enough data in the file to fill all of the variables, the 
system returns an EOF condition. All variables that have already taken values before the 
condition occurs retain their values. 
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In the program below, we OUTPUT five data items serially, and then retrieve the data items 
with a serial ENTER statement. 

10 CREATE BDAT "STORAGE"#1 
20 ASSIGN SPath TO "STORAGE" 

30 INTEGER Num»First'Fourth 

4 0 N u m = 5 

GO OUTPUT @Path iNum>"squared"equals"»Num*Num»END 
70 ASSIGN @Pat h TO "STORAGE" 

80 ENTER @Path?First»Second$»Third$'Fourth»Fifth$ 

90 PRINT First5Second$»Third$'Fourth»Fifth$ 

100 END 

5 squared equals 25. 

Note that we re-ASSIGNed the I/O path in line 70. This was done to re-position the file pointer 
to the beginning of the file. If we had omitted this statement, the ENTER would have produced 
an EOF condition. Note also that the OUTPUT statement includes END, which specifies that 
the EOF pointer is to be moved to match the file pointer at statement completion. In this case, 
the END is redundant. 

Random ENTER 

When you ENTER data in random mode, the system starts reading data at the beginning of the 
specified record and continues reading until either all of the variables are filled or the system 
reaches the EOR or EOF. If the system comes to the end of the record before it has filled all of 
the variables, an EOR condition is returned. 

In the following example, we randomly OUTPUT data to 10 successive records, and then 
ENTER the data into an array in reverse order. 

10 CREATE BDAT "SQ-R00TS>5>2*8 

20 ASSIGN @Pat h TD "S0_R0DTS" 

30 FOR Iric = 1 to 5 

40 OUTPUT SPath»Inc!Inc»SQR(Inc) 

50 NEXT Inc 

B0 FOR Inc = 5 TO 1 STEP -1 

70 ENTER SPath>Inc !Num(Inc) >Sqroot<Inc) 

80 NEXT Inc 

90 PRINT "Number" '"Square Root" 

100 FOR Inc = 1 TO 5 

110 PRINT Num(Inc)>Sqroot(Inc) 

120 NEXT Inc 

130 END 

Number Square Root 

1 1 

2 1.41421356237 

3 1.73205080757 

4 2 

5 2,23B0G79775 
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In this example, there was no need to re-ASSIGN the I/O path because the random ENTER 
automatically re-positions the file pointer. 

Executing a random ENTER without a variable list has the effect of moving the file pointer to 
the beginning of the specified record. This is useful if you want to serially access some data in 
the middle of a file. Suppose, for instance, that you have a file containing 100 8-byte records, 
and each record has a REAL number in it. If you want to read the last 50 data items, you can 
position the file pointer to the 51st record and then serially read the remainder of the file into an 
array. 


100 REAL Array(1:50) 

110 ENTER iRealpath *51 

120 ENTER iRealpath5Arrav(*) 


Single-Byte Access 

You can define records to be just one byte long. In this case, it doesn’t make sense to read or 
write one record at a time since even the shortest data type require two bytes to store a number. 

Random access to one-byte records, therefore, has its own set of rules. When you access a 


one-byte record, the file pointer is positioned to the specified byte. From there, the access 
proceeds in serial mode. Random OUTPUTS write as many bytes as the data item requires, and 
random ENTERs read enough bytes to fill the variable. The example below illustrates how you 
can read and write randomly to one-byte records. 

10 

INTEGER Int 

20 

CREATE 

BDAT "BYTE"*100*1 

30 

ASSIGN 

iBvtepath TO "BYTE" 

40 

OUTPUT 

iBv t e pat h * 153.B7 

50 

OUTPUT 

iBvtepath *353 

B0 

OUTPUT 

@B y t e p a t h * 11 5 " s t r i n sf" 

70 

ENTER 

iBytepath *951nt 

80 

ENTER 

@Bytepath * 15Real 

30 

ENTER 

iBvtepath >115 S t r $ 

100 

PRINT 

Real 

110 

PRINT 

I n t 

120 

PRINT 

St r$ 

130 

END 


3.G7 

3 

string 




Note that we had to declare the variable “Int” as an INTEGER. If we hadn’t, the system would 
have given it the default type of REAL and would therefore have required 8 bytes (also 8 
records). 
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General Mass Storage Operations 


Trapping EOF and EOR Conditions 

An EOF condition exists whenever the system attempts to read data at, or beyond, the byte 
marked by the EOF pointers. The EOR condition will arise if you attempt to randomly read or 
write beyond the particular record specified. If, for example, you try to randomly OUTPUT a 
20-character string into a 10-byte record, an EOR condition will occur. EOF conditions will also 
result whenever you try to read or write beyond the physical end-of-file. 

EOF and EOR conditions can be trapped with an ON END statement. ON END is similar to ON 
ERROR except that it only traps EOF/EOR conditions and is only applicable to the specified I/O 
path. If you do not have an ON END statement in a program, the EOF/EOR condition will 
produce an error that is trappable by the ON ERROR statement. Encountering a logical or 
physical end of file will produce Error 59. Encountering an end of record in random mode 
produces Error 60. 

You can have any number of ON END statements in a program context. ON END statements 
that refer to different I/O paths will not interfere with each other, even if the paths go to the 
same file. If you have more than one ON END to the same I/O path, the system will use 
whichever one it most recently executes during program flow. 


An ON END is cancelled by the OFF END statement. OFF END only cancels the ON END 
branch for the specified I/O path. Re-ASSIGNing an I/O path will also cancel any existing ON 
END branch for the particular path. 


The example below illustrates some of the more common situations that cause an EOF condi¬ 
tion. 

100 CREATE BDAT "ONEND" * 10 >8 
110 ASSIGN @End pat h TO "ONEND" 

120 ON END @ E n d p a t, h GOTO Eofl 

130 FOR I r. c = 1 TO 20 

140 OUTPUT OEndpath »Inc!SQR(Inc) 

150 NEXT Inc 
ISO Eofl: ! 

170 PRINT "EOF CONDITION -- ATTEMPT TO RANDOMLY WRITE BEYOND PHYSICAL END OF F 
I LE ♦ " 

180 PRINT 
190 ! 

200 ON END @Endpath GOTO Eof2 

210 OUTPUT SEndpath #5 5"THIS IS A STRING." 

220 Eof2: ! 

230 PRINT "EOR CONDITION -- ATTEMPT TO RANDOMLY WRITE DATA ITEM LONGER THAN 
RECORD. " 

240 PRINT 
250 ! 

260 ON END OEndpath GOTO Eof3 
270 ENTER @Endpath * 5 5Str$ 

280 Eo f3 : ! 

280 PRINT "EOR CONDITION -- 
300 PRINT 
310 ! 


ATTEMPT TO READ DATA ITEM LONGER THAN RECORD." 
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320 

AS8IGN @End pat h TO " 

0NEND" 

330 

ON END SEndpath GOTO 

E o f 4 

340 

FOR I n c = 1 TO 100 


350 

OUTPUT ©End path5"A 

" 

3B0 

NEXT Inc 


370 

Eo f4: ! 


380 

PRINT "EOF CONDITION 

-- ATTEMPT 

I LE ♦ 

II 


390 

PRINT 


400 

| 


410 

ASSIGN @Endpath TO " 

0NEND" 

420 

ON END @En d pa t h GOTO 

Eof 5 

430 

FOR Inc = 1 TO 100 


440 

ENTER @ E n d p a t h5St r$ 

450 

NEXT Inc 


460 

Eo f5: ! 


470 

PRINT "EOF CONDITION 

-- ATTEMPT 

I LE« 

II 


480 

PRINT 


490 

! 


500 

ON END ©End path GOTO 

Eo f 8 

510 

OUTPUT ©Endpatht5i5t 

END 

520 

ENTER ©Endpath»8 5X 


530 

Eo f6: ! 


540 
LE ♦ " 

PRINT "EOF CONDITION 

-- ATTEMPT 

550 

! 


580 

END 



READ BEYOND PHYSICAL END OF F 


EOF CONDITION -- 
PHYSICAL END OF 

ATTEMPT 

FILE* 

TO 

RANDOMLY 

WRITE 

BEYOND 

EOR CONDITION -- 
ITEM LONGER THAN 

ATTEMPT 

RECORD* 

TO 

RANDOMLY 

WRITE 

DATA 

EOR CONDITION -- 
THAN RECORD♦ 

ATTEMPT 

TO 

READ DATA 

i ITEM 

LONGER 

EOF CONDITION -- 
PHYSICAL END OF 

ATTEMPT 

FILE* 

TO 

SERIALLY 

WRITE 

BEYOND 

EOF CONDITION -- 
PHYSICAL END OF 

ATTEMPT 

FILE* 

TO 

SERIALLY 

READ 

BEYOND 

EOR CONDITION -- ATTEMPT 
LOGICAL END OF FILE* 

TO 

RANDOMLY 

READ 

BEYOND 


This example highlights a number of interesting points. First, in line 210 we try to randomly 
write a 17-byte string into an 8-byte record. The system returns an EOR condition. The length 
header for the string, however, is still 17. So when we try to read the string in line 270, we again 
receive an EOR condition. 

In line 320 we re-ASSIGN the I/O path name in order to position the file pointer to byte 1. Then 
we redefine the ON END branch. These two statements must appear in this order since re- 
ASSIGNing an I/O path has the effect of canceling any ON END branch previously associated 
with the path. 

In line 510, we shrink the file by moving the EOF pointer to the end of record 5 with the “END” 
secondary word. When we try to read record 6 in line 520 we get an EOF condition. 
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Protecting Files 

Protect codes are two-character strings that can be assigned to any BDAT, BIN or PROG type 
file with the PROTECT statement. Protect codes are not unbreakable; they are only intended to 
prevent accidentally writing in files and directories. 

For instance, the following statement assigns the protect code “AA” to the file named “FILEl.” 
PROTECT "FILEl"."AA" 

File specifiers in mass storage statements that write to a file or directory must include the protect 
code, if the file has one. Mass storage statements that read a file or directory do not require the 
protect code (e.g., CAT, LOAD, LOAD BIN, LOADSUB ALL FROM, GET and COPY). A 
protect code is specified by placing it in brackets right after the file name. To assign an I/O path 
name to the file named “FILEl,” you would now have to include the protect code. 

ASSIGN @Pathl TO "FILEl<AA>" 

If you assign a protect code longer than two characters, the system will ignore everything after 
the second (non-blank) character. For example, the protect codes LONGPASS, LOLLYPOP, 
and LOST all result in the same protect code: LO. This rule holds both for PROTECTing a file 
and for specifying the protect code in a file specifier. For instance: 

PROTECT "FILEl" ."Protectl" 

would assign the protect code “Pr” to FILEl. To rename the file, we could write: 

RENAME "FILEl<Prattle>" TO "FILE2" 

“Prattle” is an acceptable protect code, since it starts with “Pr.” Note that we do not include a 
protect code in the new file name. If you do, the system ignores it since the old protect code is 
passed to the new file name. FILE2 still has the protect code “Pr”. To rename the file again, we 
might write: 

RENAME "FILE2< P r >" TO "FILE3" 

Renaming a file has the effect of changing the file name in the directory and leaving everything 
else intact. 

In addition to using the PROTECT statement, you can also assign a protect code to a BDAT file 
when you create it. For example: 

CREATE BDAT " E x am p 1 e< x x > " *10 

creates a 10-record BDAT file called “Example” and gives it a protect code of “xx”. You can 
also do this to PROG files with the STORE and STORE BIN statements. However, since ASCII 
files cannot be protected, a protect code cannot be included in any CREATE ASCII, SAVE, or 
RE-SAVE statement. 

To change a protect code, simply execute a new PROTECT statement. To change the protect 
code of “Example” to “yy,” execute: 


PROTECT "Ex amp 1e< x x >" >" yy 
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Note that you must include the current protect code in the file specifier. 

To completely remove a protect code from a file, PROTECT the file with a code consisting of 
two blanks. For example, to remove the protect code from file “Example,” execute: 

PROTECT "Ex amp 1e< y y >" »" " 

When specifying a file that does not have a protect code, you can either ignore the code entirely 
or include a code of two spaces: 

PURGE "Example" 
or 

PURGE "Example < >" 

Securing Program Lines 

While PROTECT prevents unintentional writing into files and directories, it does not prevent a 
programmer from looking at lines in a program. The SECURE statement prevents program lines 
from being listed. 

For example, the following statement secures lines 10 thru 100 of the program currently in 
memory. 

SECURE 10*100 

If you want the entire program to be secure just execute: 

SECURE 


Note 

Once a program is secured, it cannot be UNsecured. You should keep a 
backup copy of all programs in their unsecured form. 


When you list a program, the secured lines are listed with asterisks after the line numbers. For 
example, lines 30 thru 60 are secured in the following listing. 


10 

20 

30* 

40* 

50* 

GO* 

70 

80 


! E x a m p 1 e of Secured 
! B e 3 i n p a s s w o r d c h e c K 


! End of password checK 
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Copying Files and Volumes 

The COPY statement allows you to duplicate individual files or an entire disc volume. Any type 
of file may be copied. 

COPY of a file duplicates the existing file and places the new file name in the directory. A new 
file can be created either on the same disc or on another disc. If you copy a file to the same disc, 
the new file name must be different from the existing file name. If the file is of BDAT, BIN or 
PROG type, you can also assign a protect code to the new file. If there is not enough room on 
the disc for the file to be copied, the system cancels the statement and returns an error. 

If the COPY statement specifies two mass storage volumes and no file names, a copy of the 
entire source volume is created. The purpose of this COPY option is to duplicate discs or make 
back-up copies. Note that you will lose any old information in the directory of the destination 
volume. A volume copy does not append to the contents of the destination; when the copy is 
finished, the source and destination volumes will be identical. You cannot copy a larger volume 
to a smaller volume, regardless of the amount of data on the larger volume. You can quickly 
purge all the files on a volume by copying an empty disc onto a full disc. 

Examples 

The following statement copies “Filel” from the current system mass storage device to a new 
file called “File2” on the same mass storage. 

COPY "Filel" TO "File2" 

The following statement copies “Filel” from the current system mass storage to the drive at 
interface select code 7, primary address 0, unit number 1. Note that both files can be named 
“FILE1” if they are on different volumes. 

COPY "Filel" TO "Fi1e1:HP>700>1" 

The following statement copies a file from an HP 82901 drive to the current system mass storage 
device. The new file “DATA” is given the protect code “xx.” 

COPY "Filel:HP82901*700#0" TO "DATA<xx>" 

The following statement copies the entire disc from the right-hand internal drive to the left-hand 
drive of a Model 236. 

COPY INTERNAL" TO ":INTERNAL >4 > 1 " 
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Purging Files 

You can purge a file from the directory by using the PURGE statement. Purging a file deletes 
the directory entry for the file and releases the reserved space in the data area. Purging a file, 
therefore, creates two “gaps” on the disc: one in the data area and one in the directory. When 
you create a file, the system looks at all the gaps in the data area to see if the newly created file 
will fit in any of them. 

Directory entries must be in the same order as the files in the data area. The fourth directory 
entry, for example, must correspond to the fourth file in the data area. Consequently, if you 
PURGE a file, and then create a smaller file, you may lose disc space. The following examples 
illustrate this principle. 


Suppose that you have three consecutive files on a disc with the following names and sizes. 
DIRECTORY 


ENTRY 


DATA AREA 



3 SECTORS 


4 SECTORS 


5 SECTORS 


Executing the following statement: 
PURGE "FILEB" 


creates a 1-entry gap in the directory and a 4-sector gap in the data area. 


ENTRY 

1 

2 

3 


DIRECTORY 


DATA AREA 


FILE A 


FILE C 



4 

5 


6 
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Now, suppose you create a 2-sector file: 

CREATE ASCII “FILED" .2 

The system will place this file in the data-area gap and place the directory entry in the directory 

gap- 

DIRECTORY DATA AREA 

ENTRY 



You now have a 2-sector gap in the data area but no gaps in the directory. If you create another 
file, the system will fill entry 4 in the directory and will reserve space in the data area past 
FILEC. The two unused sectors will not be reclaimed unless you PURGE one of the adjacent 
files, FILED or FILEC. 

Accessing Directories 

Disc structure and mass storage directories were briefly described earlier in this chapter. As you 
may recall, a directory is merely an index to the files on a mass storage media. The BASIC 
language has several features that allow you to obtain information from the directories of mass 
storage media. This section presents several techniques that will help you access this informa¬ 
tion. 

To get a catalog listing of a directory, you will use the CAT statement. Executing CAT with no 
media specifier directs the system to get a catalog of the current system mass storage directory. 

CAT 

Including a media specifier directs the system to get a catalog of the specified mass storage. For 
instance, executing the following statement returns a catalog of the directory of the left drive of a 
Model 236. 

CAT " : INTERNAL*4>1" 

Both of the preceding statements sent the catalog listings to the current system printer (the one 
specified in the last PRINTER IS statement; the default system printing device is the CRT). 
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Sending Catalogs to External Printers 

The CAT statement normally directs its output to the current PRINTER IS device. The CAT 
statement can also direct the catalog to a specified device, as shown in the following examples: 

CAT TO #701 

CAT TO #Externa 1_prtr 

CAT TO #Device_se1ector 

The parameter following the # is known as a device selector and is further described in Chapter 
8, “Using a Printer,” and in the Glossary of the BASIC Language Reference. 

Extended Access of Directories 

With MS, the CAT statement has the following additional capabilities: 

• additional information about PROG files may be obtained 

• the mass storage directory can be sent to a string array 

• files to be cataloged may be selected by name or by beginning letter(s) of the file name 

• the number of selected file entries may be counted 

• the CAT operation may be directed to “skip” a specific number file entries before sending 
entries to the destination 

• the catalog header may be suppressed 

Cataloging Individual PROG Files 

Performing CAT operations on an individual PROG file returns additional information about 
the file. A catalog of a PROG files yields the following information: 

• a list of the binary program(s) contained in the program file and the size of each (in bytes) 

• the size of the main program (in bytes). 

• a list of contexts (SUB and FN subprograms) and their sizes (in bytes) 

The following catalog listing is an example of a CAT performed on an individual PROG file. 
Note that this catalog format only requires 45 columns. 


NEWPAGER_A 

NAME 


SIZE TYPE 


MAIN 
FNBa r$ 

FNRoman$ 

K i 11K e y s 
FNT r i m$ 

FNUpc$ 

FNLwc$ 

Table-formatter 

Strip 

AVAILABLE ENTRIES = 0 


62002 BASIC 
3G80 BASIC 
G5G BASIC 
42G BASIC 
414 BASIC 
344 BASIC 
41G BASIC 
G810 BASIC 
12G0 BASIC 


The AVAILABLE ENTRIES table entry is not currently used. 
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If the program contai 
BASIC system and 
are not supported 
returned. 


ins a binary or PHYREC program, a warning and the version codes of both the 
the binary program are included in the catalog information. PHYREC programs 
with BASIC 3.0. The following example shows the format of the message 


ProS.phy 

NAME 


SIZE TYPE 


PHYREC 2♦0 

*** WARNING: System 
MAIN 

AVAILABLE ENTRIES = 0 


1734 BASIC BINARY 
leu el 3* Bin leu el 2* 
222 BASIC 


Cataloging to a String Array 

The following example program segment shows an example of directing the catalog of mass 


storage 

file entries t 

100 

PRINT " 

110 

PRINT 

120 

CAT TO * 

130 

PRINT "N 

140 

PRINT 

150 

! 

ISO 

PRINT " 

170 

PRINT "- 

180 

Array.si 

190 

ALLOCATE 

200 

CAT TO C 

210 

FOR Entr 

220 

PRINT 

230 

NEXT Ent 

240 

PRINT "N 

250 

PRINT 

280 

! 

270 

END 


:o the CRT and then to a string array. 

CAT to CRT." 


CRT 5 COUNT Files.and-headr ! Includes 5-line heade 
umber of f i 1 es = "5Fi1es_and_headr-5 


CAT to a strinS array*" 


ze=Files_and_headr+2 ! Allow for 7-line header* 
Cat a 1o (1:A r ray_siz e)C 8 0] 
a t a 1 o ( * ) 
y = 1 TO Array.size 
CataloS$(Entry) 
ry 

umber of files*"5Array»size-7 


r ♦ 
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The program produces the following output. 


CAT to CRT ♦ 


:INTERNAL 


VOLUME LABEL: 

B982G 




FILE NAME PRO 

TYPE REC/FILE 

BYTE/REC 

ADDRESS 

Dat a 1 

ASCII 

3 

256 

1G 

Ch ap 1 

BDAT 

3 

25G 

20 

P ro sf 1 

PROG 

2 

256 

23 

Ch ap2 

BDAT 

7 

256 

26 

P ro $2 

PROG 

2 

256 

33 

Da t a2 

ASCII 

9 

256 

35 

Ch ap3 

BDAT 

G 

256 

45 

D a t a 3 

ASCII 

5 

25G 

51 

BCD_INTR 

ASCII 

3 

256 

5G 

BCD-CONFIG 

ASCII 

9 

256 

59 

BCD-ENT1 

ASCII 

2 

256 

68 

BCD_OUT1 

ASCII 

1 

256 

70 

BCD-ENTB I N 

ASCII 

2 

256 

71 

BCD-ENTFMT 

ASCII 

10 

256 

73 

Number of fi1e s = 14 




CAT to a string array* 





:INTERNAL * 4 
LABEL: B382B 

FORMAT: LIF 

AVAILABLE SPACE: 892 


SYS FILE NUMBER 

RECORD 

MODIFIED 

PUB 

OPEN 


FILE NAME 

LEV 

TYPE 

TYPE RECORDS 

LENGTH DATE 

TIME ACC STAT 

Da t a 1 

1 


ASCII 

3 

25G 

MRW 

Ch ap 1 

1 

9 8 X G 

BDAT 

3 

25G 

MRW 

P ro $ 1 

1 

9 8 X G 

PROG 

2 

25G 

MRW 

Ch ap2 

1 

9 8 X G 

BDAT 

7 

25G 

MRW 

P ro sf2 

1 

9 8 X G 

PROG 

2 

25G 

MRW 

D a t a 2 

1 


ASCII 

9 

25G 

MRW 

Ch ap3 

1 

9 8 X G 

BDAT 

G 

25G 

MRW 

D a t a 3 

1 


ASCII 

5 

25G 

MRW 

BCD-INTR 

1 


ASCII 

3 

25G 

MRW 

BCD-CONF I G 

1 


ASCII 

9 

25G 

MRW 

BCD-ENT1 

1 


ASCII 

2 

25G 

MRW 

BCD-OUT 1 

1 


ASCII 

1 

25G 

MRW 

BCD-ENTB I N 

1 


ASCII 

2 

25G 

MRW 

BCD-ENTFMT 

1 


ASCII 

10 

256 

MRW 


Number of fi1e s = 14 


Including the keyword COUNT followed by a numeric variable returns the total number of file 
entries plus header lines to that variable; here, the variable Files_and_headris used. In this 
example, a value of 2 is added to this variable to compensate for the 7-line header which is sent 
instead of the usual 5-line header. This new value, stored in Array-size, is then used to 
direct the computer to ALLOCATE just enough space in a string-array variable to hold the 
directory listing. The program can then search the directory listing for further information, if 
desired. 
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You may have noticed that the format for catalogs sent to string arrays (the second catalog 
listing) is different from catalogs sent to the PRINTER IS device. This catalog format requires 
that each array element must be dimensioned to hold at least 80 characters with this type of 
CAT operation. Again, the header contains 7 lines, not 5 as with catalogs sent to devices. 

If the CAT operation would not have filled the string array, the unused array elements would 
have been set to the null string (i.e., strings of length 0). If there are more catalog lines than 
string-array elements, the operation stops when the array is filled. No indication of the “over¬ 
flow” is reported; the count returned is equal to the number of array elements. 

Suppressing the Catalog Header 

To suppress the catalog header that would otherwise be sent automatically to the destination, 
use the following syntax: 

CAT 5NO HEADER 

CAT TO St rinp_a r rav$(*)5 NO HEADER 
CAT "Pro S_2"5 NO HEADER 

Using NO HEADER suppresses the 5-line or 7-line heading of each catalog format shown 
above, respectively. The catalog listing of a PROG file would be 3 lines shorter. The first line of 
each catalog listing contains the first directory entry, the second element contains the second 
entry, and so forth. 

Cataloging Selected Files 

The directory entry of file(s) that begin with certain character(s) can be obtained by using the 
secondary keyword SELECT. For this example, assume that the directory contains the follow¬ 
ing entries: 


:INTERNAL 
VOLUME LABEL: 
FILE NAME PRO 

B9826 

TYPE 

REC/FILE 

BYTE/REC 

ADDRESS 

Dat a 1 

ASCII 

3 

256 

16 

Ch ap 1 

BDAT 

3 

256 

20 

P ro sf 1 

PROG 

2 

256 

23 

Ch ap2 

BDAT 

7 

256 

26 

P ro sf2 

PROG 

2 

256 

33 

D a t a 2 

ASCII 

S 

256 

35 

Ch ap3 

BDAT 

6 

256 

45 

Dat a3 

ASCII 

5 

256 

51 

BCD_INTR 

ASCII 

3 

256 

56 

BCD-CONFIG 

ASCII 

S 

256 

59 

BCD-ENT1 

ASCII 

2 

256 

68 

BCD-OUT 1 

ASCII 

1 

256 

70 

BCD-ENTBIN 

ASCII 

2 

256 

71 

BCD-ENTFMT 

ASCII 

10 

256 

73 


Suppose that you want to catalog only files beginning with the letters “Prog”. The following 
examples show how this may be accomplished. Notice that this is not the same operation as 
getting a catalog of a PROG file. 

Be9inninS_chars$="ProS" 

CATiSELECT Be Sinnin 3_c h a rs$ 


CATiSELECT 


Pros" >C0UNT Files-an d_headr 
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The directory entries of the three files beginning with the letters “Prog” are sent to the PRIN¬ 
TER IS device. In the second CAT statement above, the variable Fi les_and_head r is filled 
with the number of selected files found on the current default mass storage device (plus the 5 
header lines). (Keep in mind that the variable Files_and_headr must be currently defined in 
the current program context.) 

The following result would be sent to the system printing device. 

: INTERNAL. 4 
VOLUME LABEL: B982S 

FILE NAME PRO TYPE REC/FILE BYTE/REC ADDRESS 

Prosfl PROG 2 256 23 

Pro*2 PROG 2 25G 33 

Prosf3 PROG 2 25G 533 

SELECT may also be used to get the catalog of an individual file entry by selecting the entire file 
name, as shown in the following statement: 

CAT iSELECT "Chap3" 

Getting a Count of Selected Files 

It is often desirable to determine the total number of files on a disc, or the number that begin 
with a certain character or group of characters. The COUNT option directs the computer to 
return the number of selected files in the variable that follows the COUNT keyword. 

CAT 5 COUNT Fi1es_and_headr 

CAT ! SELECT "Data".COUNT Selected-files 

The first CAT operation returns a count of all files in the directory (plus 5 header lines), since 
not including SELECT defaults to “select all files”. The second operation returns a count of the 
specifically selected files (plus 5). 

Skipping Selected Files 

If there are many files that begin with the same characters, it is often useful to be able to skip 
some of the directory entries so that the catalog is not as long. This may be especially useful 
when using a drive such as an HP 7912, which has the capability of storing more than 10 000 
files. 

The following statement shows an example of skipping file entries before sending selected 
entries to the destination. 

CAT !SELECT "BCD" .SKIP 5 

:INTERNAL » 4 
VOLUME LABEL: B982G 

FILE NAME PRO TYPE REC/FILE BYTE/REC ADDRESS 
BCD-ENTFMT ASCII 10 25G 73 


The first five “selected” files (that begin with the specified characters) are “skipped” (i.e., not 
sent with the rest of the catalog information). 
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Including COUNT in the previous CAT operation (as shown below) returns a count of the 
selected files (plus header lines), not just the catalog lines sent to the destination. Remember 
that selected files includes all files skipped, if any. In this case, a value of 11 is returned, not 1 (or 
6) as might be expected. 

CAT 5 SELECT "BCD"»SKIP 5tCOUNT Cat a 1o 4 - 1ines 

Note that if SKIP is included, the count remains the same (as long as at least one file is 
cataloged). If the number of files to be skipped equals the number of files selected, COUNT 
returns a value of zero. 

CAT;SELECT "BCD">SKIP BLOUNT Fi les_arid_head r 

The following program shows an example of looking at the files in a catalog by viewing a small 
“window” of files at one time. The technique is useful for decreasing the amount of memory 
required to hold a catalog listing in a string array. 

100 ! Declare a small string array (7 elements)* 

110 DIM A r r a y $(1:7)[80] 

120 ! 

130 ! Send header to the array* 

140 CAT TO A r ray $(*) 

150 ! Print header* 

ISO FOR Elemental TO 7 
170 PRINT Array$(Element)Cl»453 

180 NEXT Element 
180 ! 

200 ! Now Set 7-1ine "windows" and print files therein* 

210 First_fi1e = 1 ! BeSin with first file in directory* 

220 REPEAT ! Send file entries to Array$ until last file sent* 

230 ! 

240 ! Send files to Array*? SKIP files already printed? 

250 ! return index (with COUNT) of last file sent to Array$* 

260 CAT TO Array$(*) 5SKIP First-file-l »COUNT Last_file»N0 HEADER 

270 DISP "First fi1e = "5First_fi1e i "5 Last fi1e = "5 Last_fi1e 

280 ! 

280 ! Print file entries (no entry printed when Last_file=0)* 

300 FOR Element=1 TO (Last_fi1e-First_fi1e)+1 ! (G or less)+l* 

310 PRINT A r ray$(E1emen t)C1 »4 5 3 

320 NEXT Element 

330 ! 

340 First_file=Last_file+1 ! Point to next "window*" 

350 ! 

3S0 UNTIL Last_file=0 ! Until SKIP >= number of files* 

370 ! 

380 END 


It is also important to note the order of options in the CAT statement. This order is required 
when several options are used. If the NO HEADER option is used, it must be the last option in 
the list, as shown in the following example. 

CAT 5 SELECT "BCD">SKIP 5>C0UNT Se 1 ected_fi1es >NO HEADER 
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The primary address, determined by the switch settings, is combined with the interface select 
code to make up the device selector. In the following example the primary address 01 is 
appended to the interface select code 7 to produce the device selector 701. 

PRINTER IS 701 

This statement tells the computer to use a the internal HP-IB interface (select code 7) to 
communicate with a printer whose switches are set to the primary address “01”. If the printer’s 
primary address is set to “11”, the device selector would be “711”. 

A device selector can be created mathematically by multiplying the interface select code by 100 
and adding the primary address. For example, a printer on the internal HP-IB bus whose 
primary address is set to 9 would have the device selector 709 (7 x 100 + 9 = 709). 


Switch Settings 

Five switch segments, dedicated to setting the primary address, allow thirty-two possible 
addresses. In the following decimal-to-binary conversion table, each binary digit corresponds to 
one of the switch segments. A ’1’ indicates the switch segment is on, while a ’0’ indicates the 
switch segment is off. 


Decimal 

Binary 

0 

00000 

1 

00001 

2 

00010 

3 

00011 

4 

00100 

5 

00101 

6 

00110 

7 

00111 

8 

01000 

9 

01001 

10 

01010 

11 

01011 

12 

01100 

13 

01101 

14 

OHIO 

15 

01111 


Decimal 

Binary 

16 

10000 

17 

10001 

18 

10010 

19 

10011 

20 

10100 

21 

10101 

22 

10110 

23 

10111 

24 

11000 

25 

11001 

26 

11010 

27 

11011 

28 

11100 

29 

11101 

30 

11110 

31 

11111 


A quick glance at the switch segments lets you confirm the primary address. 
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Using Device Selectors 

A device selector is used by several different statements. In each of the following, the numeric 
constant is a device selector. 


PRINTER IS 1 
PRINTER IS 701 

PRINTER IS 22 
CAT TO #701 
PRINTALL IS 707 

LIST #701 


Specifies the internal CRT. (default) 

Specifies a printer with interface select code 7 and switch selected to 
primary address 01. 

Specifies a printer connected through interface select code 22. 
Prints a disc directory at 701. 

Logs information on a printer whose select code is 7 and whose 
switches are set to primary address 07 (binary 00111). 

Lists the program in memory to a HP-IB printer set to primary 
address 01. 


Most statements allow a device selector to be assigned to a variable. Either INTEGER or REAL 
variables may be used. 

PRINTER IS Hal 
CAT TO #Do 3 


The following three-letter mnemonic functions have been assigned useful values. 


Mnemonic Value 

PRT 701 

KBD 2 

CRT 1 


For example, the following statements perform the same action. 

PRINTER IS PRT 
PRINTER IS 701 

The mnemonic may be used anywhere the numeric device selector can be used. 

Another method may be used to identify the printer within a program. An I/O path name may 
be assigned to the printer; the printer is subsequently referenced by the I/O path name. This 
technique is fully explained in the BASIC Interfacing Techniques manual. 
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Chapter 


8 


Introduction 

Sooner or later it needs to be printed. A wide range of printers, supported by BASIC, can be 
connected to the Series 200 computers. This chapter covers the statements commonly used to 
communicate with external printers. The following list names some of the printers that work with 
Series 200 computers: 

• HP 2631 Dot Matrix Printer 

• HP 2671 Thermal Printer 

• HP 2673 Intelligent Thermal Printer 

• HP 9866 Thermal Printer (with interface) 

• HP 9876 Thermal Graphics Printer 

• HP 82905 Dot Matrix Printer 

• HP 2601 Daisy-Wheel Printer 

All these printers, except the HP 9866, can be directly connected to the computer’s internal HP-1B 
interface. The HP 9866 requires its own interface. 

Fundamentals 

The PRINT statement normally directs text to the screen of the CRT. Text may be re-directed to 
an external printer by using the PRINTER IS statement. The default system printer is the 
screen of the CRT. The PRINTER IS statement is used to change the system printer. 

Before a printer will print the first character, several steps are required to set up the printer. 
These steps are fully documented in the appropiate printer installation manual. 

After the printer is switched on and the computer and printer have been connected via an 
interface cable, there is only one piece of information needed before printing can begin. The 
computer needs to know the correct device selector for the printer. This is analogous to 
knowing the correct telephone number before making a call. 
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Device Selectors 

A device selector is a number that uniquely identifies a particular device connected to the 
computer. When only one device is allowed on a given interface, it is uniquely identified by the 
interface select code. In this case, the device selector is the same as the interface select code. 

For example, the internal CRT is the only device at the interface whose select code is 1. To 
direct the output of PRINT statements to the CRT, use the following statement. 

PRINTER IS 1 

This statement defines the screen of the CRT to be the system printer. Until changed, the output 
of PRINT statements will appear on the screen of the CRT. 

When more than one device can be connected to an interface, such as the internal HP-IB 
interface, (interface select code 7) the interface select code no longer uniquely identifies the 
printer. Extra information is required. This extra information is the primary address. 

Primary Addresses 

Each printer has a set of switches, usually located on the back panel, which determine the 
primary address of the printer. 

The following photographs show the switch locations on various printers. In addition to the 
primary address switch segments there are usually segments that control the printers response 
to other signals on the HP-IB bus. 



8 BIT ASCII -n LISTEN 

SH1 AH 1T6TE0L3LE0SR1RL0PP0DC0DT0C0 sRQ-n C ALWAYS 

, , . .-:—L-ly I -- - - 

' -••••>•> - *\ \\ 


o 

7 BIT ASCII 


ilium 


j 


CAUTION: refer servicing to qualified personnel 
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Using the External Printer 

Most ASCII characters are printed on an external printer just as they appear on the screen of the 
CRT. Depending on your printer, there will be exceptions. Several printers will also support an 
alternate character set: either a foriegn character set, a graphics character set, or an enhanced 
character set. If your printer supports an alternate character set, it usually is accessed by sending 
a special command to the printer. 

Control Characters 

In addition to a “printable” character set, printers usually respond to control characters. These 
non-printing characters generally produce a response from the printer. The following table 
shows some of the control characters and their effect. 


Printer’s Response 

Control Character 

ASCII Value 

ring printer’s bell 

ctrl-G 

7 

backspace one character 

ctrl-H 

8 

horizontal tab 

ctrl-I 

9 

line-feed 

ctrl-J 

10 

form-feed 

ctrl-L 

12 

carriage-return 

ctrl-M 

13 


One way to send control characters to the printer is the CHR$ function. Execute the following. 

PRINTER IS 701 
PRINT CHR$(12) 

The printer responds with a formfeed. To resume printing on the internal CRT, execute the 
following. 

PRINTER IS 1 

PRINT “Back to the CRT." 

Other control characters may be valid for your printer. For example, sending a control-N to the HP 
82905A printer changes the character size (font) of subsequent text. 

10 PRINTER IS 701 
20 B i £f$ = CHR$ (14) 

30 PRINT BIT$5"Double-Width Text" 

40 PRINTER IS CRT 
50 END 

Refer to the appropriate printer manual for a complete listing of control characters and their 
effect on your printer. Some control characters will only affect the current line of text. 
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Escape-Code Sequences 

Similar in uss to control characters, escape-code sequences allow additional control over most 
printers. These sequences consist of the escape character, CHR$(27), followed by one or more 
characters. 

For example, the HP 2631 printer is capable of printing characters in several different fonts. To 
print extended characters on the HP 2631 an escape code sequence is sent to the printer before the 
actual text to be printed is sent. 


10 

PRINTER IS 701 


20 

Es c$ = CHR$(27) 


30 

B i 3 $ = " 8 k 1S" 


40 

Re$ular$="8:k0S" 


50 

PRINT Esc$5BiS$5"Extended 

-Font Text" 

GO 

PRINT Esc$5Re3ular$!"Back 

to no renal ♦ " 

70 

PRINTER IS 1 


80 

END 



Many escape code sequences can be used by more than one printer. For instance, the HP 2671 
and the HP 2631 share the same escape code sequence for underlining text. 

10 PRINTER IS PRT 

20 Under$ = CHR$ ( 27 ) 8:" 8:dD" 

30 No rma1$ = CHR$(27)&"8d@" 

40 PRINT “This is not underlined" 

50 PRINT Un d e r$& : " Th i s is un d e r 1 i n e d "&No rma 1 $ 

GO PRINT "Done*" 

70 PRINTER IS CRT 

80 END 


Since each printer may respond differently to control characters and escape code sequences, 
check the manual that came with your printer for details concerning their use. 
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Formatted Printing 

For many applications the PRINT statement provides adequate formatting. The simplest 
method of print formatting is by specifying a comma or semicolon between printed items. 

When the comma is used to seperate items the printer will print the items on field boundries. 
Fields start in column one and occur every ten columns (columns 1,11,21,31,...). Using the 
values: A = 1.1 B = —22.2 C = 3E + 5 D = 4.4E + 8 

PRINT A >C fD 
Produces: 

123456789012345678901234567890123456789 

1.1 -22.2 300000 5.1E+8 

Note the form of numbers in a normal PRINT statement. A positive number has a leading and a 
trailing space printed with the number. A negative number uses the leading space position for 
the sign. This is why the positive numbers in the previous example appear to print one 
column to the right of the field boundries. The next example shows how this form prevents 
numeric values from running together. 

PRINT A 5B !C5D>E 

123456789012345678901234567890123 

1.1 - 22.2 300000 5 . 1 E + 8 

Using the semicolon as the separater caused the numbers to be printed as closely together as 
the “compact” form allows. The compact form always uses one leading space (except when the 
number is negative) and one trailing space. 

The comma and semicolon are often all that is needed to print a simple table. By using the 
ability of the PRINT statement to print the entire contents of of a array, the comma or semicolon 
can be used to format the output. 

If each array element contained the value of its subscript, the statement: 

PRINT Array(*)5 

Produces: 

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14... 

Another method of aligning items is to use the tabbing ability of the PRINT statement. 

PRINT TAB(25) 5-1.414 

123456789012345678901234567890123 

-1.414 


While PRINT TAB works with an external printer, PRINT TABXY will not. PRINT TABXY may 
be used to specify both the horizontal and vertical position when printing to the internal CRT. 
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A more powerful formatting technique employs the ability of the PRINT statement to allow an 
image to specify the format. 

Using Images 


Just as a mold is used for a casting, an image can be used to format printing. An image specifies 
how the printed item should appear. The computer then attempts to print the item according to 
the image. 

One way to specify an image is to include it in the PRINT statement. The image specifier is 
enclosed within quotes and consists of one or more field specifiers. A semicolon then separates 
the image from the items to be printed. 

PRINT USING " D.DDD"5PI 

This statement prints the value of pi (3.141592659...) rounded to three digits to the right of the 
decimal point. 

3.142 


For each character “D” within the image, one digit is to be printed. Whenever the number 
contains more non-zero digits to the right of the decimal than provided by the field specifier, the 
last digit is rounded. If more precision is desired, more characters can be used within the image. 

PRINT USING "D,10D"5 PI 

3.141592G536 


Instead of typing ten “D” specifiers, one for each digit, a shorter notation is to specify a repeat 
factor before each field specifier character. The image “DDDDDD” is the same as the imaae 
“6D”. 


The image specifier can be included in the PRINT statement or on it’s own line. When the 
specifier is on a different line, the PRINT statement accesses the image by either the line 
number or the line label. 


100 Format: IMAGE "SZ.DD" 

110 PRINT USING Format 5A»B>C 
120 PRINT USING 100 5 A »B»C 


Both PRINT statements use the image in line 100. 
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Numeric Image Specifiers 

Several characters may be used within an image to specify the appearance of the printed value. 


Image 

Specifier 

Purpose 

D 

Replace this specifier with one digit of the number to be printed. If the digit is a leading zero, 
print a space, if the value is negative, the position may be used by the negative sign. 

Z 

Same as “D” except that leading zeros are printed. 

E 

Prints two digit of the exponent after printing the sequence “E + This specifier is equal to 
“ESZZ”. See the Language Reference for more details. 

K 

Print the entire number without leading or trailing spaces. 

S 

Print the sign of the number: either a “ + ” or “ - ”. 

M 

Print the sign if the number is negative; if positive, print a space. 


Print the decimal point. 

H 

Similar to K, except the number is printed using the European number format (comma 
radix). (Requires IO) 

R 

Print the comma (European radix) (Requires 10) 

* 

Like Z, except that asterisks are printed instead of leading zeros. (Requires IO) 


To better understand the operation of the image specifiers examine the following examples and 
results. 


Statement 

Output 

PRINT 

USING 

"K" ! 33.BBS 

33♦GB6 

PRINT 

USING 

"DD.DDD"533.EGG 

33♦GGG 

PRINT 

USING 

"DDD.DD"j 33.GGG 

33 ♦ 67 

PRINT 

USING 

"ZZZ.DD"533.GGG 

033*67 

PRINT 

USING 

"zzz"; ,aaa 

000 

PRINT 

USING 

"ZZZ" ; .555 

001 

PRINT 

USING 

"SD.3DE"5G.023E+23 

+6♦023E+23 

PRINT 

USING 

"S3D.3DE"5G.023E+23 

+602♦300E+21 

PRINT 

USING 

"S5D.3d e"5G.023E+23 

+60230♦000E+19 

PRINT 

USING 

"H"53121.55 

3121>55 

PRINT 

USING 

"DDRDD"510.35 

19 >95 

PRINT 

USING 

" ***" 5.555 

**1 


To specify multiple fields within the image, the field specifiers are separated by commas. 


Statement 

PRINT USING "K >5D >5D"5100.200 >300 100 

PRINT USING "DD *ZZ >DD"51>2 >3 102 


Output 

200 300 

3 
















262 Using a Printer 


If the items to be printed can use the same image, the image need be listed only once. The 
image will then be re-used for the subsequent items. 

PRINT USING "5D.DD">3.98 >5.95 >27.50 >133.95 


123458789012345678901234587890123 
3.98 5.95 27.50 139.95 

The image is re-used for each value. An error will result if the number cannot be accurately 
printed by the field specifier. 


String Image Specifiers 

Similar to the numeric field image characters, several characters are provided for the formatting 
of strings. 


Image 

Specifier 

A 


_ Purpose _ 

Print one character of the string. If all characters of the 
trailing blank. 


string have been printed, print a 


K Print the entire string without leading or trailing blanks 
X Print a space. 


“literal 


1 > 


Print the characters between the quotes. 


The following examples show various ways to use string specifiers. 
PRINT USING "5X.10A>2X>10A"5"Tom" ."Smith" 

12345878901234567890123458789 
Tom Smith 

PRINT USING "5X»""John"" »2X»10A" ! "Smith" 

12345878901234587890123458789 
John Smith 

PRINT USING .PART NUMBER"" ,2x>1Qd"590001234 

12345878901234567890123458789 


PART NUMBER 


90001234 
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Additional Image Specifiers 

The following image specifiers serve a special purpose. 


Image 

Specifier 

Purpose 

B 

Print the corresponding ASCII character. 

This is similar to the CHR$ function. 

# 

Suppress automatic end-of-line sequence. 

L 

Send the current end-of-line (EOL) sequence; with 10, see the PRINTER IS statement in the 
BASIC Language Reference manual for details on re-defining the EOL sequence. 

/ 

Send a carriage-return and a linefeed. 

@ 

Send a formfeed. 

+ 

Send a carriage-return as the EOL sequence. 

(Requires 10) 

— 

Send a linefeed as the EOL sequence. 

(Requires 10) 


For example: 

PRINT USING *#" outputs a formfeed. 

PRINT USING "D »X >3A >""OR NOT"" tXt B ,X , B»B"i2>"BE" »50»GG>GS 
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Special Considerations 

If nothing prints, check if the printer is ON LINE. When the printer if OFF LINE the computer 
and printer can communicate but no printing will occur. 

Sending text to a non-existent printer will cause the computer to wait indefinitely for the printer 
to respond. ON T IMEOUT may be used within a program to test for the printer. To clear the 
error press (CLR I/O) , check the interface cable, and switch settings then try again. 

Since the printer’s device selector may change, keep track of the locations in the program 
where a device selector is used. If most of the program’s output is sent to a printer, you may 
wish to use the PRINTER IS statement at the beginning of the program and then send messages 
to the CRT screen by using the OUTPUT statement. 

PRINTER IS 701 

PRINT "Text to the printer." 

OUTPUT 1 5 "Sc reen Message" 

PRINT "Back to the printer." 

If the program must use the PRINTER IS statement frequently, assign the device selector to a 
variable; then if the device selector changes, only one program line will need to be changed. 
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The Real-Time Clock 


Chapter 


Introduction 

The internal clock provides the date, time of day, and interval timing to one-hundredth of a second 
resolution. In this chapter you will find the statements and functions used to set and read the clock. 
Additional statements, allow you to define event-initiated branches based on the clock’s value. 

Many of the statements presented in this chapter require CLOCK. 

Internally, the clock maintains the year, month, day, hour, minute, and second as a single real 
number. This number is scaled to an arbitrary “dawn of time” thus allowing it to also represent 
the Julian date. The current value of the clock is returned by the TIMEDATE function. 

PRINT TIMEDATE 

While the value returned contains all the information necessary to uniquely specify the date and 
time to the nearest one-hundredth of a second, it needs to be “unpacked” to provide under¬ 
standable information. 

The following functions are available to extract the date and time of day from TIMEDATE. 

The DATE$ function extracts the date from the value of TIMEDATE. 

PRINT DATE$(TIMEDATE) 

Prints: 1 Mar 1900 

This is the default power-up date for machines without the powerfail option. 

The TIMES function returns the time of day. 

PRINT TIME$(TIMEDATE) 


Prints: 00:05:27 
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Until the clock has been set to the correct time of day, the TIME$ function returns the time since 
power-up (on machines without the powerfail option). 

The SET TIMEDATE statement is used to set the clock 

SET TIMEDATE DATE <" 1 OCT 1982") + T I ME("8:37:30"> 

The time of day can be changed without affecting the date by the SET TIME statement. 

SET TIME TI ME("9:55" ) 

Clock Time 

To minimize the space required to store the date and time, and yet insure a unique value for 
each point in time, both time and date are combined as a single real number. This value is the 
Julian date multiplied by the number of seconds in a day. By recalling that there are 86400 
seconds in a day, the date and time of day can be extracted from TIMEDATE by the following 
simple alogrithms. 

TIMEDATE MOD 86400 returns the time of day, and 

TIMEDATE DIO 86400 returns the Julian date. 

The time of day is expressed in seconds past midnight and is easily divided into hours, minutes, 
and seconds. The Julian date requires a bit more processing to extract the month, day, and year 
but this method insures a unique value for each day over the entire range of the clock (1 Mar 
1900 through 4 Aug 2079). 
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Year 

1900 

1910 

1920 

1930 

1940 

1950 

1960 

1970 

1980 

1990 

2000 

2010 

2020 

2030 

2040 

2050 

2060 

2070 

2080 


Clock Time 

Clock Value 
2.086578144E+11 
2.089733472E+11 
2.092888800E+11 
2.096044992E+11 
2.099200320E+11 
2.102356512E+11 
2.105511840E+11 
2.108668032E+11 
2.111823360E+11 
2.114979552E+11 
2.118134880E+11 
2.121291072E+11 
2.124446400E+11 
2.127602592E+11 
2.130757920E+11 
2.133914112E+11 
2.137069440E+11 
2.140225632E+11 
2.143380960E+11 


Hours 

1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 


Seconds 

3600 

7200 

10800 

14400 

18000 

21600 

25200 

28800 

32400 

36000 

39600 

43200 

46800 

50400 

54000 

57600 

61200 

64800 

68400 

72000 

75600 

79200 

82800 

86400 
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Setting the Time 

The time of day is changed by SET TIME X, where X is the number of seconds past midnight. The 
value of X must be in the range: 0 through 86399.99 seconds. The TIME function will convert 
twenty-four hour formatted time (HH:MM:SS) into the value needed to set the clock. 

The TIME function converts an ASCII string representing a time of day, in twenty-four hour 
format, into the number of seconds past midnight. For example: 

SET TIME TIME<"15:30:10") 

Is equivalent to: 

SET TIME 55810 

Either of these statements will set the time of day without changing the date. Use the SET 
TIMEDATE statement to change the date. 

To display the new time, the TIMES function formats the clock’s value (TIMEDATE) into hours, 
minutes, and seconds. 

PRINT TIME$(TIMEDATE) 

Prints: 15:30:16 

Even though TIMEDATE returns a value containing both time of day and the Julian date, 
TIMES performs an internal modulo 86400 on the value passed to the function and will always 
return a string in the range: 00 : 00 : 00 thru 23:59:59. 

The following program contains the routines to set and display the time of day. The routines are 
written as user-defined functions that may be appended to a program. Once appended to a 
program, the routines duplicate the TIME and TIMES functions available with CLOCK. The format¬ 
ted time can then be displayed by the following statement. 

PRINT FNTime$(TIMEDATE) 


Prints: 15:31:05 
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Given the clock’s value, the FNTime$ function returns the time of day in 24 hour format 
(HH:MM:SS). The FNTime function converts the time of day to seconds and is used to set the 
clock. 


10 Show-time:DISP FNTime*(TIMEDATE) 

20 GOTO Show-time 

30 END 

40 ! 

50 ! While the program is running# type: 

GO ! SET TIME FNTI ME("11:5:30") 

70 ! then press <EXECUTE> to show the new time. 

80 ! 

90 I********************************************************* 

100 ! 

110 D E F F N Tim e $(N o w) ! Given 'SECONDS' Return ' h h:m m:s s ' 

120 ! 

130 Now=INT(Now) MOD 86400 

140 H = Now DIO 3G00 

150 M = Now MOD 3600 DIO GO 

1 GO S = Now MOD GO 

170 OUTPUT T$ USING " *t ZZ»K"»H»": " #M»": " »S 

180 RETURN T$ 

190 FNEND 

200 ! 

210 DEF FNTime(T$) ! Given 'hh:mm:ss' Return 'SECONDS' 

220 ! 

230 ON ERROR GOTO Err 

240 ENTER T$5H*MtS 

250 RETURN (3600*H+G0*M+S) MOD 86400 

2G0 E r r:OFF ERROR 

270 RETURN TIMEDATE MOD 8G400 

280 FNEND 


After entering the program, follow the instructions at the beginning of the program to verify 
correct operation. Store this program in a file named “FUNTIME”. The functions can be 
extracted from this program and appended to other programs by the LOADSUB statement. 

Note that the FNTime function requires hours, minutes, and seconds, while the TIME function 
only requires hours and minutes. 








270 The Real-Time Clock 


Setting the Date 


The date is changed by SET TIMEDATE X, where X is the Julian date multiplied by the number of 
seconds in a day (86400). The DATE function converts a formatted date (DD MMM YYYY) into the 
value needed to set the clock. Due to the wide range of values allowed by the DATE function, 
negative years can be specified, but not when using the function to set the clock. 

The following statement will set the clock to the proper date. 

SET TIMEDATE DATE(" 1 June 1984") 

When programming without CLOCK, the user-defined function FNDate can be used. 

SET TIMEDATE FNDate("1 June 1384") 

Both of these statements are equivalent to the following statement. 

SET TIMEDATE 2.11321G992E+ 11 

The DATE and FNDate functions convert the accompanying string (or string expression) into the 
numeric value needed to set the clock. To read the clock, the DATE$ and FNDateS functions 
format the clock’s value as the day, month, and year. For example, the following line will print the 
date. 

PRINT DATE$(TIMEDATE) 

Prints: 1 Jun 1984 

Programs that need to run without can use the following user-defined functions appended to the 
end of the program. These functions simulate the DATE and DATES keywords available in 
CLOCK. The algorithm is valid over the entire range of the clock. 

Note the following functions are restricted to values the clock will accept, the DATE and DATES 
functions available with CLOCK allow a much wider range of values (including negative years). 

10 Show-date: DISP FNDate$(TIMEDATE) 

20 GOTO Show_date 

30 END 


40 

50 

BO 

70 

80 

90 

100 

110 

120 

130 

140 

150 

ISO 

170 

180 

190 

200 

210 

220 

230 

240 


DEF FNDate$(Seconds) ! Given 'SECONDS' Return 'dd mmm yyyy 



Julian=Seconds DIO 8G400-1721119 
Year=(4*Julian-l) DIO 14G097 
Julian=(4*Julian-l) MOD 14G097 
Day=Julian DIO 4 
Julian=(4*Day+3) DIO 14G1 
Day=(4*Day+3) MOD 14G1 
Day=(Day+4) DIO 4 

Month=(5*Day-3) DIO 153 ! Month 

Day=(5*Day-3) MOD 153 


DATA JAN »FEB»MAR>APR >MAY»JUN»JUL»AUG fSEP »0CT >N00 *DEC 
DIM Month$(1:12)[3] 

READ Mon t h$(*) 


While the program is running type: 

SET TIMEDATE FNDATEC1 JAN 82") <EXECUTE> 
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250 Day = (Day + 5) DIO 5 ! Day 

2G0 Year=100*Year+Julian ! Year 

270 IF Mor.th<10 THEN 

280 Morith = Month+3 

290 ELSE 

300 Month=Month-9 

310 Year=Year+l 

320 END IF 

330 OUTPUT D$ USING "#>ZZ»X»3A»Xt4Z"5Day#Month$<Month> »Year 

340 RETURN D$ 

350 FNEND 
380 ! 

370 DEF FNDate(Dmy$) ! Given 7 dd mmm yyyy 7 Return 'SECONDS 7 
380 ! 

300 DATA JAN »FEB>MAR,APR t MAY>JUN > JUL>AUG tSEP >0CT »N0M»DEC 

400 DIM Mon t h$(1:12)C 3 3 

410 READ Month$(*) 

420 ! 

430 ON ERROR GOTO Err 

440 I$ = Dmy$8c M 

450 ENTER 1$ USING "DD>4A»5D"iDay»M$ t Ye ar 

480 IF YearClOO THEN Ye ar = Ye ar+1000 

470 FOR 1=1 TO 12 

480 IF POS(M$ >Month$(I ) ) THEN Month = I 

490 NEXT I 

500 IF Month = 0 THEN Err 

510 IF Month >2 THEN 

520 Month=Month-3 

530 ELSE 

540 Month=Month+9 

550 Year=Year-1 

580 END IF 

570 Century=Year DIM 100 

580 Remainder=Year MOD 100 

590 Ju1ian=14G097*Century DIM 4+1481*Remainder DIM 4+(153*Month+2) DIM 5+Day 

+1721119 

GOO Ju1ian = Ju1ian*88400 

810 IF Ju1ian<2♦08882912E +11 OR Ju1ian> = 2♦143252224E+11 THEN Err 

820 RETURN Julian ! Return Julian date in SECONDS 

830 ErriOFF ERROR ! ERROR in input* 

840 RETURN TIMEDATE ! Return current date* 

850 FNEND 

Store the program in a file named “FUNDATE”. Later the functions can be appended to other 
programs by the LOADSUB statement. 


The functions FNDate$ and FNDate format the date as “DD MMM YYYY”, where DD is the 
day of the month, MMM is the first three letters of the month, and YYYY is the year. The 
function FNDate will accept the last two digits of the year. See line 460. Note that the FNDate 
function requires two digits for the day, while the DATE function does not. 


Different formats require only slight modification. By changing the following lines, the date is 
formatted as “MM/DD/YYYY”. 

330 OUTPUT D$ USING "# »2D >A >2D »A >2D"5 Mon t h 5"/"iDay 5"/"I Ye a r 

450 ENTER 1$ USING "* , ZZ>K"iMonth5DayiYear 

European date format is obtained by swapping the month and day in the above statements. 
When changing the format, be sure to switch both functions. 

If the all numeric format is chosen, delete the three lines in each function that load the array 
with the month mnemonics. 
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Using the Routines 

The following statements summarize setting and displaying the clock. 

SET TIMEDATE FNDateC'12 DEC 1981") + FNT i me ( " 13 : 44 : 15 " ) 

SET TIME FNTime("8:30:00") 

PRINT FNTime$(TIMEDATE ) 

DISP FNDate$(TIMEDATE) 

It is important to note that SET TIMEDATE expects a date and time while the DATE function 
and the user-defined function FNDate return only a date. This effectively sets the clock to 
midnight of the date specified. 


To keep the functions short, minimal parameter checking is performed. Additional checking 
may be incorporated within the functions or within the calling context. If FNDate or FNTime 
cannot correctly decode the input, the current value of the clock is returned. 


The date and time functions can be used with the following program shell to provide a “friend¬ 
ly” interface to the clock. 


10 

20 

30 

40 

50 

SO 

70 

80 

90 

100 

110 

120 

130 

140 

150 

ISO 

170 

180 

190 

200 

210 

220 

230 

240 

250 

2G0 

270 

280 

290 

300 

310 

320 

330 

340 

350 

3S0 


! PROGRAM SHELL FOR SETTING TIME AND DATE♦ 

j 

! REQUIRES THE TIME AND DATE FUNCTIONS♦ 

! 

DIM Day$(0:6 )LSI 

DATA Monday t T u e s d a yWednesday^Thursday *F rid a y^Saturday t Sunday 
READ Day$(#) 

j 

ON ERROR GOTO Nofun ! Test if functions 

Dmy$=FNDate$(TIMEDATE) ! have been loaded 

Hms$=FNTime$(TIMEDATE) 

OFF ERROR 

Main: j Get NEW date 

GOSUB Clear_5c reen 
F$ = CHR$(255)&:CHR$(72) 

! 

PRINT TABXY(1#14)5"Enter the date# and press CONTINUE*" 

OUTPUT 2 USING "* * 11A»2A" !Dmy$*F$ 

INPUT Dmy$ ! WAIT for INPUT 

I 

ENTER Dmy$ USING "2D#4A»5D" !D#M$#Y 
GOSUB Clear_sc reen 
! 

PRINT TABXY(l#14)5"Enter the time of day and press CONTINUE" 
OUTPUT 2 USING "#* 11A»2A"5Hms$*F$ 

INPUT Hms$ 

ENTER Dmy$ USING "2D #4A #5D"5 D #M$ # Y 

SET TIMEDATE FNDate(Dmy$)+FNTime(Hms$) 

! 

GOSUB Clear_5c reen 

W=(TIMEDATE DIO 8G400) MOD 7 ! Day of weeK 
PRINT TABXY(1 *1) ! "Th e clock has been set to:" 

PRINT TABXY(1 #3)5Day$(W) »" " iDmy$i" "»FNTime$(TI MEDATE) 

GOTO Quit 
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1 


370 ! 

380 ! ************ SUBROUTINES ************ 

390 ! 

400 Clear.sc reen:OUTPUT 2 USING "#>B"5255,75 
410 RETURN 

420 Nofun:PRINT "The TIME & DATE FUNCTIONS must be appended»" 

430 PRINT "(uia LOADSUB) before program will work*" 

440 Quit:END 
450 ! 

460 ! ************* FUNCTIONS ************** 

470 ! 

480 ! append time and date functions here 

The program tests to see if the functions have been loaded by trying to use them. If they are not 
loaded the program ends with an error message. With CLOCK, this program can still be used. 
Replace the calls to the user-defined functions with the appropriate keywords. The error trapping 
can then be deleted. 

To append the functions, execute the following statements while the demonstration program is 
in memory. 

LOADSUB ALL FROM "FUNDATE" 

LOADSUB ALL FROM "FUNTIME" 

Examine the program to be sure the functions have been loaded. 

The program will prompt for the date and time, then set the clock accordingly. A program such 
as this may be used as the system start-up program for applications requiring the date or time. 

Day of the Week 

An advantage of Julian dates is the simplicity of finding the day of the week. 
TIMED ATE DIM 8G400 MOD 7 returns a number which represents the day of the week. 
Monday is represented by zero (0), and the numbering continues through the week to Sunday 
which is represented by six (6). See the previous program for an example of using this routine. 

Days Between Two Dates 

The number of days between two dates is easily calculated as the following program demons¬ 
trates. 

10 ! Days between two dates 

20 INPUT "ENTER THE FIRST DATE (DD MMM YYYY)",D 1 $ 

30 INPUT "ENTER THE SECOND DATE (DD MMM YYYY)"»D2$ 

40 Days=(DATE(D2$)-DATE(Dl$>) DIO 86400 

50 DISP Days 5" days between , ";D1$5" / and /,, ;D2$;" ,n 

60 END 
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Interval Timing 

Timing a single event of short duration is quite simple. 


10 T0=TIMEDATE ! Start 

20 FOR J=1 TO 5555 

30 ! 

40 NEXT J 

50 T1=TIMEDATE ! Finish 

GO ! 

70 PRINT "It took " i DR0UND(T1-TOf3)»"seconds" 

80 END 


Programs can and should be written so that they do not change the setting of the clock. A short 
program, which simulates a stopwatch, allows interval timing without changing the clock. 

10 ! P ro 3 ram s STOPWATCH 

20 ! Interval timins without chansins the clock 

30 ON KEY 5 LABEL " START " GOTO Start 

40 ON KEY 6 LABEL " STOP “ GOTO Hold 

50 ON KEY 7 LABEL " RESET " GOTO Reset 

GO ON KEY 8 LABEL " LAP “ GOSUB Lap 

70 ! 


80 Re s e t: PR I NT CHR$(12) 

! form-feed 

80 H = 0 

! Set all 

100 M=0 

! to 

110 S=0 

! zero* 

120 ! 


130 Hold:DISP TAB(8) i H i ":" i M i ":" ! S 

! Ha i t til 

140 GOTO Hold 

! keypress 

150 ! 


1 GO Lap:PRINT H ! ":“ iM i ": " !S 

! Print lap 

170 RETURN 


180 ! 


180 Start:Z=3G00*H+60*M+S-TIMEDATE 

! Elapse d - 

200 Loop:T=(TIMEDATE+Z) MOD 8G400 

! time 

210 T=INT(T*100)/100 

! *01 sec* 

220 H=T DIO 3G00 

! Hours 

230 M=T MOD 3G00 DIO GO 

! Minutes 

240 S=T MOD GO 

! Seconds 

250 DISP TAB(8) iS 

! Show time 

2G0 GOTO Loop 

! Do aSain 

270 END 
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Accuracy 

The computer’s crystal controlled clock maintains the time to one one-hundredth of a second, 
however when timing events over a long period of time, the accuracy of the crystal must be 
considered. Under normal operating conditions, this error will be less than ± 5 seconds per day. 

If the powerfail option is installed, accuracy is improved. Under normal operating conditions, 
the powerfail clock error is less than ±2.5 seconds per day. 


Powerfail Protection 

Without the powerfail option, each time power is applied the date is initialized to March 1, 1900 
(2.08662912E + 11 seconds). If powerfail is installed, a second clock located on the powerfail 
board takes over the timekeeping function and maintains the date and time when the computer is 
turned off. (The powerfail option is not available on the Model 216.) 
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Branching on Clock Events 

Several additional branching statements, available with CLOCK, allow end-of-statement branches 
to be triggered according to the real-time clock’s value. 

• ON TIME enables a branch to be taken when the clock reaches a specified time of day. 

• ON DELAY enables a branch to be taken after a specified number of seconds has elapsed. 

• ON CYCLE enables a recurring branch to be taken with each passage of a specified 

number of seconds. 

The specified time can range from 0.01 thru 167772.15 seconds for the ON CYCLE and ON 
DELAY statements and 0 thru 86399.99 seconds for ON TIME. The value specified with ON 
TIME indicates the time of day (in seconds past midnight) for the branch to occur. 

Each of these statements has a corresponding statement to cancel the branch (OFF TIME, OFF 
DELAY, and OFF CYCLE). A statement is also canceled by executing another ON TIME ON 
DELAY, or ON CYCLE statement. 

All of the statements use the internal real-time clock. Care should be taken to avoid writing 
programs that could change the clock’s setting during execution. Since only one resource is 
dedicated to each statement, certain restrictions apply to the use of these statements. 

Cycles and Delays 

Both the ON CYCLE and ON DELAY statements enable a branch to be taken as soon as the 
specified number of seconds has elapsed. ON CYCLE remains in effect, re-enabling a branch 
with each passage of time. For example: 

10 ON CYCLE 1 GOSUB Five ! Print 5 random numbers eve rv second* 

20 ON DELAY G GOTO Quit ! After G seconds quit* 

30 ! 

40 T: DISP TIME$(TIMEDATE) ! Show the time* 

50 GOTO T 
GO ! 

70 Fiu e:F0R 1 = 1 TO 5 
80 PRINT RND5 

90 NEXT I 
100 PRINT 
110 RETURN 
120 ! 

130 0uit:END 

The program will print five random numbers every second for six seconds and then stop. 

Only one ON CYCLE and one ON DELAY statement can be active in a program context. 
Executing a second ON CYCLE or ON DELAY statement in the same program context deacti¬ 
vates the first ON CYCLE or ON DELAY statement. If a branch is missed, due to priority 
restrictions or execution of a subprogram, the event is logged and the branch will be taken 
when the restriction is removed or the original context is restored. If an active ON CYCLE or 
ON DELAY statement gets canceled in an alternate context (subprogram) the branch is re¬ 
stored when execution returns to the defining context. (See Branching Restrictions for more 
information about this). 
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Time of Day 

The ON TIME statement allows you to define and enable a branch to be taken when the clock 
reaches a specified time of day, where time of day is expressed as seconds past midnight. Using 
the TIME function simplifies setting an ON TIME statement by allowing a formatted time of day 
to be used. For example: 

ON TIME TI ME("11:30") GOTO Lunch 

Typically, the ON TIME statement is used to cause a branch at a specified time of day. By 
adding an offset to the current clock value, the ON TIME statement can be used as an interval 
timer. In the following example, both ON DELAY and ON TIME are used as interval timers. 

10 ON DELAY 5 GOSUB Takeoff ! delay 5 seconds 

20 ON TIME (TIMEDATE+10) MOD 86400 GOSUB Touchdown ! delay 10 seconds 

30 PRINT "STARTING*♦♦ "»TIME$(TIMEDATE) 

40 Clock:DISP TIME$(TIMEDATE) 

50 GOTO Clock 

60 ! 

70 Takeoff SPRINT "TAKEOFF at " *T IME$(TIMEDATE) 

80 RETURN 

SO Touchdown:PRINT "TOUCHDOWN at ">TIME$(TIMEDATE) 

100 RETURN 

110 END 

The starting time is printed when the program is executed. Five seconds later the first sub¬ 
routine is executed. Ten seconds after the program starts, the second subroutine is executed. 

Only one ON TIME statement can be active in a program context. If a branch is missed, due to 
priority restrictions or execution of a subprogram, the event is logged and the branch will be 
taken when the restriction is removed or the original context is restored. If an active ON TIME 
statement gets canceled in an alternate context (subprogram) the branch is restored when 
execution returns to the defining context. (See Branching Restrictions for more information 
about this). 

Due to the “match an exact time” nature of the ON TIME statement, if the specified time occurs 
when the statement is temporarily canceled (by an OFF TIME in an alternate context), no 
branch will be taken when the defining context is restored. 

Priority Restrictions 

A priority can be assigned to the branch defined by ON CYCLE, ON DELAY, and ON TIME. 
For example: 

□ N CYCLE Seconds (Priority GOTO Label 
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If the system priority is higher than the branch priority at the time specified for the branch, the 
event will be logged but the branch will not be taken until the system priority falls below the 
branch priority. An example program follows. 


10 COM Start 

20 P = 0 

30 Up:P = P+1 

! Priority from 1 thru 15 


110 W:GOTO M 
120 Quit:END 


130 ! -— —---- SUB has priority of G_____________ 

140 SUB Busy 
150 COM Start 

ISO PRINT "SUB" i 

170 WHILE I<10 

180 IF TIMEDATE>Start+l THEN ! Has ON CYCLE time been exceeded? 

I 8 ® PRINT 5 ! YES (only prints if Priority<7) 

200 ELSE 

210 PRINT "! NO 

220 END IF 

230 1=1+1 j Loop ten times 

240 WAIT .1 

250 END WHILE 

2G0 PRINT "DONE"! 

270 SUBEND 


Save the start-time for subproSram. 

New priority every second if not Busy. 
DELAY overrides CYCLE until priority 


40 IF P>15 THEN Quit 

50 PRINT 

SO PRINT "Priority:"iPi 

70 Start=TIMEDATE 

80 ON CYCLE l.P RECOVER Up 

90 ON DELAY .5,6 CALL Busy 


Once the priority assigned to the ON CYCLE statement is greater than the priority assigned to 
the ON DELAY statement (6) the subprogram will be interrupted. After running the program, 
change line 80 in the above program to the following: 

80 ON CYCLE 1#P GOTO Ur 

Running the new version of the program will show that GOTO (or GOSUB) will not interrupt a 
subprogram regardless of the assigned priority. The branch will be logged but not taken until 
execution returns to the main program. If you write a program that makes extensive use of 
subprograms and branching statements, use CALL and RECOVER to insure proper operation. 
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Branching Restrictions 

Certain restrictions apply to the use of ON TIME, ON CYCLE, and ON DELAY because only 
one resource is dedicated to each statement. Assuming an active branch has been defined in 
the main program, execution of a subprogram which sets up a new branch, will cause the loss of 
the original time. When the main program context is restored, the original branch will be 
restored, but at the time defined in the subprogram. The following program will illustrate this 
effect. 

10 COM Counter 

20 Counte r = 0 

30 GINIT 

40 GRID 1»1 ! Fill Graphics raster with arid* 

50 DISP Counter 

GO ON CYCLE 2 CALL Flash ! Flash Graphics every 2 seconds* 

70 W: GOTO W 
80 END 


90 !- SUB to flash Graphics raster- 

100 SUB Flash 

110 COM Counter 

120 GRAPHICS ON 

130 Counter=Counter+1 

140 DISP Counter 

150 IF Counter=5 THEN ! Change CYCLE value during fifth CALL* 

1G0 ON CYCLE ♦1 t2 CALL Quit ! New value (*1) will replace old (2)* 

170 ! Flash will end before Quit Sets called* 

180 END IF 

100 GRAPHICS OFF 

200 SUBEND 

210 !-SUB that won't Set called - 

220 SUB Quit 

230 PRINT "PROGRAM HAS STOPPED" 

240 STOP 


250 SUBEND 


The program starts out by flashing the graphics raster on and off every two seconds. When the 
subprogram’s ON CYCLE statement is activated during the fifth call to the subprogram, the 
new value (0.1 second) replaces the old value (2.0 seconds) and the program begins flashing 
the graphics raster at the new rate. Note that the branch to the second subprogram (Quit) is not 
executed because the first subprogram is finished before the specified time. To see the second 
subprogram execute, insert the following line. 

191 WAIT 1 

The delay caused by the WAIT statement allows the subprogram’s ON CYCLE statement to 
branch to the second subprogram and stop execution. 
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If an active branch defined in the main program is canceled in a subprogram (by OFF TIME, 
OFF DELAY, or OFF CYCLE) any branch missed during the execution of the subprogram will 
be lost. When the context containing the original statement is restored, the branch will be 
reactivated and processing will continue as if no branch was missed. 


10 ON DELAY 1 GOTO Done ! GOTO "Done" in one second. 

20 CALL Busy ! Call to "Busy" taKes two seconds. 

30 ! 

40 PRINT "THIS WON'T BE PRINTED UNLESS BRANCH IS CANCELED BY THE SUB" 

50 ! 

GO Don e:PR I NT "THIS LINE WILL BE PRINTED EVERY TIME" 

70 END 

80 ! - 

90 SUB Busy 

100 WAIT 2 

110 ! OFF DELAY ! RUN then remove the "!" on this line and RUN aSain. 

120 SUBEND 


By removing the comment symbol (!) from the beginning of line 110, the OFF DELAY state¬ 
ment will be executed causing any branch that has already been logged to be canceled and 
allow line 40 to be printed. 


Since branches only occur at the end of a line, no branch can be taken during an INPUT or 
LINPUT statement. The following program shows a method of monitoring the keyboard with¬ 
out preventing branches to be taken. 


10 ON KBD GOTO Yes 

20 ON DELAY 3 GOTO Gone 

30 DISP "PRESS A KEY" 

40 W: GOTO W 
50 ! 


! If Key is pressed So 
! If no keypress in 3 

! Wait here until keyp 


s e t 

new 

v a 1 

ue ♦ 

seconds 

use 

defaults 

r e s s 

o r 

en d 

of delay 


60 YessOFF DELAY ! Someone is there* 

70 OFF KBD 

80 LINPUT "NEW UALUE?",A$ 

90 DISP "USING",A$ 

100 GOTO More 

110 ! 

120 Gone:DISP ! Nobody there* 

130 DISP "USING DEFAULTS" 

140 ! 

150 Mo re:WAIT 2 

ISO DISP "program continues*♦♦ 

170 END 


The program waits a few seconds for a response. Processing continues with default values if no 
key is pressed. Pressing a key will cause the program to accept the new information. 
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Chapter 

10 


Introduction 

It is very unlikely that a computer could perform useful work without receiving input. Much of that 
input is from electronic devices: instruments, mass storage devices, other computers, and so on. 
Because a computer is an electronic device, it is very good at these tasks. There are also times when 
the computer’s input must come from the human sitting in front of the computer. 

Good human interfaces do not happen without some effort from the programmer. In many prog¬ 
rams, at least one fourth of the code is dedicated to human interface. It is not unusual to use one 
half of a good program for operator interaction, error trapping, explanatory messages, etc. 
Obviously, these estimates depend upon many factors, like the task being performed and the 
intended operators. If you are the only person who uses a program, that program may not need a 
quality human interface. However, the demands for a good human interface rise greatly if a 
program is used by many people with different backgrounds. When the intended users do not 
understand computers, your program must be very skillfully written so that it does not intimidate 
the operator or make great demands. 

This chapter introduces two of the elements of a human interface: displaying text for the operator to 
read and accepting operator input from the keyboard. These are certainly not the only elements in 
a human interface. A good human interface can involve the placement of hardware, use of graphic 
and voice communication, data base management, artificial intelligence theories, and much more. 
However, you must begin somewhere. Despite the incredible technology growing up around them, 
many programmers fail at the basic task of sending and receiving text. Hopefully, the hints in this 
chapter will help your present programs and whet your appetite for more eleborate improvements 
in future programs. 
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Displaying and Prompting 

One of the simpler things to do for the operator is to display an explanation of what is happening or 
what is expected. In the early days of computers, memory was a scarce and expensive resource. 
Old-time programmers were encouraged to use as little memory as possible. It seemed as though 
there was a contest to see who could put the most information into a 32-character message. Please 
realize that those days are over. For example, in the Model 236, there is no significant restriction on 
program size, the standard machine is shipped with over a half-million characters of memory, and 
there are 18 lines of 80 characters visible at all times on the CRT. If you are sending your operator 
tiny, cryptic 32-character messages, you are making an unnecessary mistake. 

Giving instructions to the operator can be viewed as two basic steps: 

1. Clear the CRT. 

2. Use as much of the CRT as necessary to give readable instructions. 

Determining Screen Width 

The first step in dealing with the CRT is finding out the size of the CRT. Programs written for Series 
200 computers can be used on either 50, 80 or 128-column displays. There is a CRT status register 
that contains the width of the CRT. If you are developing programs that will be transported between 
models, status register 9 will be very helpful to you. The screen width is useful in centering displays, 
labeling softkeys, formatting tabular data, and other display tasks. The following statement places 
the screen width in a variable called Crt.width. 

STATUS 1>95Crt_width 

There is also a SYSTEMS function that returns useful information about the CRT. The specifier 
“CRT ID” returns a string containing (amoung other things) the screen width and availability of 
highlights and graphics. The following example shows one method of determining the screen width 
with SYSTEMS. 

120 Test$=SYSTEM$("CRT ID") 

130 Screen=UAL(Test$C3>6]) 

Clearing the CRT 

It is embarassing to the programmer and confusing to the operator when two or more displays 
combine in an unplanned manner. The culprits are “left-over” alpha and “left-over” graphics. 
Left-over alpha can occur for a number of reasons: 

• The operator may have used the knob or cursor-control keys to scroll text from the off-screen 
buffer. 

• With TABXY, the PRINT statement overwrites any old characters on a line with new charac¬ 
ters. However, if the old text is longer than the new text, the end of the old line remains visible. 
Therefore, the following sequence does not print three blank lines. It just moves the print 
position. Any old lines will still be on the screen. 

100 PRINT 
110 PRINT 
120 PRINT 

• If the PRINTALL mode is on, all interactions on the display line and keyboard input line are 
sent to the output area. 
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Turning Off Unwanted Modes 

There are several modes that affect the appearance of the CRT. These are very useful for certain 
purposes, but generally undesirable for the display of simple text. Graphics is an obvious example. 
Left-over graphics can be removed by the following statement on non-bit mapped displays. 

GRAPHICS OFF 

The PRINTALL mode is canceled by writing a zero in the PRINTALL control register. This is 
keyboard register 1, so it has an interface select code of 2. The following statement turns off the 
PRINTALL mode. 

CONTROL 2 *1 50 

The DISPLAY FUNCTIONS mode can make a display look sloppy. This is CRT register 4, so it has 
an interface select code of 1. The following statement turns off the DISPLAY FUNCTIONS mode. 

CONTROL 1*450 

Printing Blank Lines 

To print a line that is blank is a different operation from sending only an end-of-line sequence. A 
PRINT statement with no parameters simply sends an end-of-line sequence. If the print position is 
at the start of a blank line when PR I NT is executed, that line remains blank. However, if there is text 
on that line, the text remains. This is not to say that it is “wrong” to use PRINT with no parameters. 
It just means that you cannot guarantee the output of a blank line by using PRINT with no 
parameters. 

To print a blank line, blanks must be printed. One of the most convenient ways to send a line full of 
blanks is the TAB function. Here is a sequence that prints three blank lines: 

100 STATUS 1*95 Screen 

110 PRINT TAB(Screen) 

120 PRINT TAB(Screen) 

130 PRINT TAB(Screen) 

Using OUTPUT KBD... 

The PRINT statement does not provide functions like “home” and “clear”, but the keyboard 
drivers do. Note that this is true even for keyboards which do not have a “home” key. These 
functions are invoked by sending a “Non-ASCII Key Sequence” to interface select code 2 (KBD). 
Sending characters with OUTPUT KBD is like telling the computer to press its own keys. Although 
some techniques that use the keyboard buffer are very complex (see Chapter 9 of BASIC Interfac¬ 
ing Techniques), controlling the CRT output area is simple. 

To see how this technique works, let’s use the ( CLR SCR ) Key ( ( Clear display ) on HP 46020A) as an 
example. Open your BASIC Language Reference to the end of the “Useful Tabl es” sectio n. Find 
the heading “Second Byte of N on-ASCII Key Sequences (Numeric)”. Locate the ( CLR SCR ) key on 
your computer. It is a shifted ( CLR LN ) (on non-HP 46020A keyboards). The number in that 
position is 75. Like the heading says, that is the value of the second byte of a sequenc e. The first 
byte always has a value of 255 for non-ASCII keys. Therefore, to “press” the ( CLR SCR ) key, send 
the bytes 255 and 75 to the keyboard; interface select code 2. 
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1480 

□N KEY 8 LABEL " Roman 

" GOTO 

Numbers 

1490 

□N KEY 9 LABEL " START 

" GOTO 

Be S i n 

1500 

ELSE 

j 

Use Ions labels 

1510 

ON KEY 5 LABEL "Command 

D e 1 i m " 

GOTO C o m m a nd 

1520 

ON KEY 8 LABEL " Select 

Drive " 

GOTO Drive 

1530 

ON KEY 7 LABEL " Stand, 

F m t * ? " 

GOTO Standard 

1540 

ON KEY 8 LABEL "Roman Numeral?" 

GOTO Numbers 

1550 

ON KEY 9 LABEL " START 

PRINT " 

GOTO BeSin 

1580 

END IF 



1570 

ON KEY 0 GOTO Not.used 

j 

Turn off unused Keys 

1580 

ON KEY 1 GOTO Not.used 



1500 

ON KEY 2 GOTO Not.used 



1 BOO 

ON KEY 3 GOTO Not.used 



1810 

ON KEY 4 GOTO Not.used 



1820 

| 



1830 

Spin: GOTO Spin 

j 

Wait for softkey interrupt 

1840 

! 



1850 

Not.used: ! 



1880 

BEEP 300 t ♦ 1 

i 

Feedback for unused keys 

1870 

GOTO Spin 



1880 

! 



1890 

Command: ! 



1700 

IF C m d $ = " \ " THEN 

I 

Choose command delimiter 

1710 

C m d $ = " A " 



1720 

ELSE 



1730 

Cmd$="\" 



1740 

END IF 



1750 

GOTO Menu 



1780 

! 



1770 

D r i v e : ! 



1780 

IF Disc$="RIGHT" THEN 

! 

Choose text source 

1700 

MASS STORAGE IS " :INTERNAL »1" 


1800 

Disc$="LEFT " 



1810 

ELSE 



1820 

MASS STORAGE IS ":INTERNAL »4 *0" 


1830 

Disc$="RIGHT" 



1840 

END IF 



1850 

GOTO Menu 



I860 

! 



1870 

Standard: ! 



1880 

IF Std.fmt THEN 

! 

Choose text format 

1890 

St d.fmt = 0 



1900 

ELSE 



1910 

Std.fmt = 1 



1920 

END IF 



1930 

GOTO Menu 



1940 

j 



1950 

Numbers: ! 



I960 

IF Roman THEN 

i 

Choose numeral type 

1970 

Roman = 0 



1980 

ELSE 



1990 

R o m a n = 1 



2000 

END IF 



2010 

GOTO Menu 



2020 

l 



2030 

Be sin : ! 



2040 

OUTPUT 2 5 C1 e a r$ 5 

! 

Clear CRT 

2050 

OFF KEY 

j 

Remove selection menu 

2080 

! 



2070 

! Program continues here when user presses "START" 

2080 

j 




The program uses softkeys 5 through 9. If you have an HP 46020A keyboard, your softkeys are 
labeled 1 through 8. You can modify the program to use the softkeys most useful for your 
applications. 
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It is always good programming practice to declare all variables. The first two lines do this. Next, the 
variables are given their starting values. Initialization is completed by turning off unwanted modes 
and clearing the CRT. 

The section at “Menu” displays a description and current status for each menu item. This example 
shows some of the parameters that might be used by a simple text-printing program. The items 
used are representative only. A real text formatter would have many more parameters (all the more 
reason to present them clearly). The operator can choose the following: 

• Back-slash or up-caret as a command delimiter 

• Right or left disc drive for the source of the text 

• Standard or alternate format for the text 

• Page numbering with Arabic or Roman numerals 

Notice some important aspects of this menu. All items have default values and all defaults are visible 
simultaneously. This is very important. It is irritating and confusing when an operator must answer 
question after question to get a program to begin. It is far better to show the default environment 
and allow a single keypress to start the program if the defaults are acceptable. If any defaults need 
to be changed, the operator changes only those items he wants to change. He can press “START” 
at any time, and in this simple case, never answers any questions. The operator wants a printout, 
not a game of “20 questions”. 

The current state of all items is displayed in a form that is meaningful to the operator. It is 
reasonably safe to assume that all operators know what “RIGHT” and “LEFT” mean. Very few 
would have any idea what “: INTERNAL,4,1” means. Programmers need to learn about concepts 
like “mass storage unit specifier”. Operators shouldn’t be bothered by such things. Likewise, don’t 
expect anyone to answer “1” or “0” to a question that should be answered “YES” or “NO”. 

A more technical aspect of this menu is the method used to update the display. Since the scrolling 
keys are on one side of the softkeys and the knob is on the other side, it is reasonable to assume 
that the operator might accidentally move the display out of place. One way to correct this would be 
to start each display update with a “clear screen” sequence. This guarantees the state of the CRT 
and the print position. Unfortunately, it also causes a very undesirable “blinking off” of the display 
each time a key is pressed. A constantly disappearing menu is very distracting. 

The objective is to give the impression that nothing changed except the selected item. Therefore, 
the “clear” sequence is sent before the first display only. Subsequent updates use a “home” 
sequence to ensure the position of the text, and a TABXY to set the print position. As a result, the 
new menu is written on top of the old menu. (The same visual effect could be achieved by using 
individual TABXY functions to access each item display, but that is a more difficult program to 
write.) 

Since the old display is overwritten each time, it is important to erase all unneeded characters. 
Notice that the “NO” displays are padded with a trailing blank to erase the “S” left over from 
“YES”. This technique can be extended to clear old displays of unknown length. The following 
example displays a number and erases any remaining digits from the old number. The variable 
Screen contains the screen width. 


1300 PRINT Value 5TAB(Sc reen) 
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The function uses a local copy of the string just in case you need the actual input for some other 
purpose in the main program. The response is trimmed and placed in uppercase. Then the first 
letter is tested. Four cases are identified: the answer was “Y” (for yes), the answer was “N” (for no), 
no answer was given, or the answer was not recognized. 


2000 DEF FNYes ()•($> 

2010 DIM Teinp$[ 1 ] 

2020 Temp$[ 1 »1 ] =TRIM$ (>•<$) 

2030 SELECT Temp$ 

2040 CASE "Y"»"y" 

2050 RETURN 1 

20GO CASE "N" >" n" 

2070 RETURN 0 

2080 CASE " " 

2090 RETURN -1 

2100 CASE ELSE 

2110 RETURN -2 

2120 END SELECT 

2130 FNEND 

As mentioned previously, every question should have a default answer. The default answer for a 
yes/no question depends greatly upon the nature of the question. If you are asking the operator for 
permission to use standard, reasonable parameters for an operation, then “yes” is a helpful default. 
If you are asking for permission to initialize a disc and destroy all files, then the default answer had 
better be “NO”! When a question or choice occurs more than once in a program, it is usually a 
good technique to use the operator’s previous response as the default. Put yourself in the user’s 
place and think about how the program should run. 

To use t his functio n to best advantage, the result must be tested thoughtfully. If the operator simply 
presses ( CONTINUE ) , the result will be -1. Therefore, the default should be assumed if FNYes = - 1. 
A “yes” answer is indicated by FNYes = 1; whereas a non-negative answer can be tested simply as 
IF FNYes. A non-affirmative answer is FNYesCl. Any result less than zero is a noncommittal 
reply. Perhaps the default could be assumed for any negative result, or perhaps a negative result 
should cause the question to be repeated. The test IF NOT FNYes reveals a negative reply. As 
you can see, many shades of interpretation are possible. 

Custom Interfaces 

The ON KBD statement can be used to design very effective keyboard interfaces. However, these 
are usually very complex to program. In fact, using ON KBD to accept keyboard input, CRT 
highlights to display a cursor, and PRINT TABXY to position cursor and text is essentially writing a 
text editor. Unfortunately, programs of that magnitude are beyond the scope of this manual. 
Information about the applicable keywords can be found in the BASIC Language Reference, and 
some examples of CRT control and ON KBD can be found in Chapters 8 and 9 of BASIC 
Interfacing Techniques. 
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Chapter 

11 


Introduction 

Most programs are subject to errors happening at run time, even if all the typographical/syntactical 
errors have been shaken out in the process of entering the program into the computer in the first 
place. There are three courses of action to take with respect to errors: 

1. Try to prevent the error from happening in the first place 

2. Once an error occurs, try to recover from it and continue execution 

3. Do nothing — let the program roll over and die if an error happens 

The last alternative, which may seem frivolous at first glance, is certainly the easiest to implement, 
and the nature of HP desktop computers is such that this is often a feasible choice. Upon en¬ 
countering a run-time error, the computer will pause program execution, and display a message 
giving the error number and the line in which the error happened, and the programmer can then 
examine the program in light of this information and fix things up. The key word here is “pro¬ 
grammer”. If the person running the program is also the person who wrote the program, this 
approach works fine. If the person running the program did not write it, or worse yet, does not 
know how to program, some attempt should be made to prevent errors from happening in the first 
place, or to recover from errors and continue running. 
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Anticipating Operator Errors 

When a programmer writes a program, he or she knows exactly what the program is expected to 
do, and what kinds of inputs make sense for the problem. Given this viewpoint, there is a strong 
tendency for the programmer not to take into account the possibility that other people using the 
program might not understand the boundary conditions. A programmer has no choice but to 
assume that every time a user has the opportunity to feed an input to a program, a mistake can be 
made and an error can be caused. If the programmer’s outlook is noble, he or she will try to save 
the user from needless anguish and frustration. If the programmer’s outlook is self-centered, he or 
she will try to keep from getting involved in future support problems. In either case, an effort must 
be made to make the program foolproof. 

Boundary Conditions 

A classic example of anticipating an operator error is the “division by zero” situation. An INPUT 
statement is used to get the value for a variable, and the variable is used as a divisor later in the 
program. If the operator should happen to enter a zero, accidentally or intentionally, the program 
crashes with an error 31. It is far better to be watching for an out-of-range input and respond 
gracefully. One method is shown in the following example. 


1 0 0 

INPUT “Miles traveled and total 

hours 1 ' * M i 1 e s tHours 

110 

IF Hours=0 THEN 


120 

BEEP 


130 

PRINT “Improper value entered 

for hours*" 

lao 

PRINT “Try atfain ! " 


150 

GOTO 100 


1 GO 

END IF 


170 

Mph=Miles/Hours 



Consider another simple example of giving a user the choice of six colors for a certain bar graph. It 
might be preferable to have the user pick a number corresponding to the color he wished to choose 
instead of having to type in up to six characters. In this case, the program wouldn’t have to check 
for each number, but rather it could use the logical comparators to check for an entire range: 

4030 OUTPUT KBD 501ea r$ 5 ! Clear the screen 

4040 DATA GREEN (BLUE tRED >YELL0W >PURPLE »PINK 
4050 ALLOCATE Co 1 ors$(1 : B)CS] 

4060 READ Colors$(#) 

4070 FOR 1=1 TO 6 

4080 PRINT USING "DD»X>K"51 »Co1ors$<I) 

4090 NEXT I 

4100 Ask: INPUT "Pick the number of a color" »I 
4110 IF I>=1 AND I< =6 THEN Valid-Color 
4140 BEEP 

4150 DISP "Invalid answer -- "5 

4160 WAIT 1 

4170 GOTO Ask 

The above example needs a little extra safeguarding. I, the variable being input, should be declared 
to be an integer, since the only valid inputs are 1, 2, 3, 4, 5, and 6. An answer like “pick the 3.14th 
color listed” does not make sense. 
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Real number boundaries are tested for in a manner similar to that of integers: 


7010 INPUT "Enter the waveform's frequency (in KHz)"»Frequency 
7020 IF F r e q u en c y< = 0 THEN 7 010 

7030 INPUT "Enter the amplitude (0-10 v o 11 s ) " t A m p1it ud e 

7040 IF A m p1it ud e < 0 DR A m p 1it ud e >10 THEN 703 0 

7050 INPUT "Enter the phase a n S1 e (in decrees) "»Ari$le 
7060 IF AnsfleCO DR An si e >180 THEN 7050 
7070 An S1e = An S1e *PI/180 


REAL Numbers and Comparisons 

A word of caution is in order about the use of the = comparator in conjunction with REAL (full 
precision) numbers. Numbers on this computer are stored in a binary form, which means that the 
information stored is not guaranteed to be an exact representation of a decimal number — but it 
will be real close! What this means is that a program should not use the = comparator in an IF 
statement where the comparison is being performed on REAL numbers. The comparison will yield 
a ’false’ or ’0’ value if the two are different by even one bit, even though the two numbers might 
really be equal for all practical purposes. 

There are two ways around this problem. The first is to try to state the comparison in terms of the 
< = or > = comparators. However if it’s absolutely necessary to do an equality comparison with a 
pair of REAL numbers, then the second method must be used. This involves picking an error 
tolerance for how close to being equal the two numbers can be to satisfy the test. 

Real number line <-» 

XI X2 

TO —» 

So if the difference between two REAL numbers XI and X2 is less than or equal to a tolerance TO, 
we’ll say that XI and X2 are “equal” to each other for all practical purposes. The value of TO will 
depend upon the application, and must be chosen with care. 

For an example, assume that we’ve picked a tolerance of 10“ 12 for comparing two REAL numbers 
for equality. The proper way to compare the two numbers would be: 

950 IF ABS(X1-X2K = 1E-12 THEN Numbers.eiual 
9G0 ! Otherwise they're not equal 

Another technique for comparing REAL values is to use the DROUND function. This is especially 
suited to applications where the data is known to have a certain number of significant digits. For 
more details on binary representations of decimal numbers, refer to Chapter 4. 
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Error Trapping 

Despite the programmer’s best efforts at screening the user’s inputs in order to avoid errors, 
sometimes an error will still happen. It is still possible to recover from run time errors, provided the 
programmer predicts the places where errors are most likely to happen. 

ON/OFF ERROR 

The ON ERROR command sets up a branching condition which will be taken any time a recover¬ 
able error is encountered at run time. The branching action taken may be either GOTO, GOSUB, 
CALL, or RECOVER. GOTO and GOSUB are purely local in scope — that is, they are active only 
within the context in which the ON ERROR is declared. CALL and RECOVER are global in scope 
— after the ON ERROR is set up, the CALL or RECOVER will be executed any time an error 
occurs, regardless of subprogram environment. 

When an ON ERROR statement is executed, the language system will make sure that the specified 
line or subprogram exists in memory before the program will proceed. If ON ERROR GOTO/ 
GOSUB/RECOVER are specified, then the line identifier must exist in the current context. If an ON 
ERROR CALL is given, then the specified subprogram must currently be in memory. In either case, 
if the system can’t find the given line, an error 49 is issued. 

If either ON ERROR GOSUB or ON ERROR CALL are used and an error occurs, the specified 
branch will take place, and when the RETURN or SUBEXIT is executed, then program execution 
will resume at the line which caused the error, and an attempt will be made to execute the line 
again. 

ON ERROR has a priority of 16, which means that it will always take priority over any other ON 
<event> since the highest user-specifiable priority is 15. 

The OFF ERROR statement will cancel the effects of the ON ERROR statement, and no branching 
will take place if an error is encountered. 

The DISABLE statement has no effect on ON ERROR branching. 

ERRN/ERRL/ERRM$ 

ERRN is a function which returns the error number which caused the branch to be taken. ERRN is a 
global function, meaning it can be used from the main program or from any subprogram, and it will 
always return the number of the most recent error. 

ERRM$ is a string function which returns the text of the error which caused the branch to be taken. 

ERRL is a function which is used to find the line in which the error was encountered. ERRL is a 
boolean function. The program feeds it a line identifier, and either a 1 or a 0 is returned, depending 
upon whether or not the specified identifier indicates the line which caused the error. ERRL is a 
local function, which means it can only be used in the same environment as the line which caused 
the error. This implies that ERRL cannot be used in conjunction with ON ERROR CALL, and that it 
can be used with ON ERROR GOTO and ON ERROR GOSUB. ERRL can be used with ON 
ERROR RECOVER only if the error did not occur in a subprogram which was called by the 
environment which set up the ON ERROR RECOVER. 
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The ERRL function will accept either a line number or a line label. 

1140 DISP ERRL(710) 

910 IF ERRL (Compute ) THEN F i x_coutput e 

ON ERROR GOSUB 

The ON ERROR GOSUB statement should only be used when you can guarantee that the problem 
causing the error can be fixed and the line can be re-executed safely. Remember that if the action 
taken in the error service routine is not sufficient to correct the problem, the program will dive into 
an infinite loop. Every time an error occurs, a GOSUB will cause a branch to the error service 
routine which will RETURN execution to the line causing the error. 

When an error triggers a branch as a result of an ON ERROR GOSUB statement being active, 
system priority is set at the highest possible level (16) until the RETURN statement is executed, at 
which point the system priority is restored to the value it was when the error happened. 

100 Radical=B*B-4*A#C 
110 Im a 3in a r y = 0 

120 ON ERROR GOSUB Esr 
130 Partial=SQR(Radical) 

140 OFF ERROR 


350 Esr: 

IF ERRN=30 THEN 

3G0 

I m a i i n a r y = 1 

370 

Radical=ABS(Radical) 

380 

ELSE 

390 

BEEP 

400 

DISP "Unexpected Error 

410 

PAUSE 

420 

END IF 

430 

RETURN 


("5ERRN 5") " 


ON ERROR GOTO 

The ON ERROR GOTO statement is generally more useful than ON ERROR GOSUB, especially if 
you are trying to service more than one error condition. The only advantage that ON ERROR 
GOSUB has over ON ERROR GOTO is that system priority is maintained at the highest possible 
level until the error subroutine is finished. 

By using the ON ERROR GOTO statement, the same error service routine can be used to service all 
the error conditions in a given context. By testing both the ERRN (what went wrong) and the ERRL 
(where it went wrong) functions, proper recovery procedures can be taken. 
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10 RESTORE 
20 PRINT 

30 PRINT 

40 PRINT “Coefficients of quadratic equation A" 
50 DATA 0*0*0 

GO READ A,B>C 

70 Max real = 1.7976931348G231E + 308 

GO Ouer f 1 o w = 0 

90 Coefficients: ! 

100 INPUT “A?" ,A 
110 IF A=0 THEN 

120 DISP "Must be quadratic" 

130 WAIT 1*5 

140 GOTO Coefficients 


150 

END IF 


160 

PRINT "A="5 

A 

170 

INPUT "B? " * 

B 

180 

PRINT "B = " 5 

B 

190 

INPUT "C?", 

C 

200 

PRINT "C=" ; 

C 

210 

C o m p u t e _ r o o t s 

: ; 

220 

ON ERROR GOTO Esr 


230 Im a Sin a r y = 0 

240 Pa r11 = -B/(2♦*A) 

250 Part2=SQR(B*B-4*A*C)/(2♦#A) 

260 IF NOT Imaginary THEN 

270 Root1=Part1+Part2 

280 Root2=Partl-Part2 

290 END IF 

300 OFF ERROR 

310 Print_roots: ! 


320 

330 

340 

350 

360 

370 

380 

390 

400 


IF Ima Sina ry = 0 

'Root 1 
'Root 2 


THEN 

= "5Root 1 
= " ? R o o 12 


PRINT 
PRINT 
ELSE 

PRINT "Root 1 =";Partl5" +"5Part25" i" 
PRINT "Root 2 =";Parti; n -";Part2!" i" 

END IF 

IF Ouerflow THEN PRINT "OOERFLOW" 

STOP 
410 Esr: ! 

420 IF ERRN = 30 THEN ! SQR OF NEGATIOE NUMBER 

430 Part2=SQR(ABS(B*B-4*A*C))/(2*A) 

440 ImaSinary=l 

450 Branch=l 

4G0 GOTO 270 

470 ELSE 

480 IF ERRN=22 THEN ! REAL OOERFLOW 

490 0 u e r f1o w =1 

500 SELECT 1 

510 CASE ERRL(240) 

520 Part 1=SGN(B)*SGN<A)*Maxreal 

530 Branch=2 

540 CASE ERRL(250) 

550 Par12 = Maxre a 1 

560 Branch=3 

580 CASE ERRL(270) 

590 Roo11=Maxrea 1*SGN(Part1) 

GOO Branch=4 

620 CASE ERRL(280) 

G30 Root2 = Max real*SGN(Parti) 

G40 Branch=5 

GGO PRINT "UNEXPECTED OOERFLOW" 

670 Branch=G 

680 CASE ELSE 

S90 DISP "UNEXPECTED ERROR"5ERRN 

700 Branch=G 

710 END SELECT 

720 END IF 

730 END IF 

740 ON Branch GOTO 270#250>260>280»290 * 10 
750 END 
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ON ERROR CALL 

ON ERROR CALL is global, meaning once it is activated, the specified subprogram will be 
called immediately whenever an error is encountered regardless of the current context. System 
priority is set to level 16 inside the subprogram, and remains that way until the SUBEXIT is 
executed, at which time the system priority will be restored to the value it was when the error 
happened. 

The ON ERROR CALL statement should only be used when you can guarantee that the 
problem causing the error can be fixed and the line can be re-executed safely. Remember that if 
the action taken in the error service routine is not sufficient to correct the problem, the program 
will dive into an infinite loop. Every time an error occurs, a CALL will cause a branch to the 
error service routine which will return execution to the line causing the error when a SUBEXIT 
statement is executed. 

Bear in mind that an ON...CALL statement cannot pass parameters to the specified subpro¬ 
gram, so the only way to communicate between the environment in which the error is declared 
and the error service routine is through a COM block. 

The ERRL function will not work in a different environment than the one in which the ON 
ERROR statement is declared, so when using an ON ERROR CALL, you should set things up in 
such a manner that the line number either doesn’t matter, or can be guaranteed to always be 
the same one when the error occurs. This can be accomplished by declaring the ON ERROR 
immediately before the line in question, and immediately using OFF ERROR after it. 


5010 ON ERROR CALL Fix-disc 
5020 ASSIGN SFile TO "Data_file" 

5030 OFF ERROR 
5040 ! 

5050 ! 

5060 ! 

7020 SUB Fix-disc 
7030 SELECT ERRN 
7040 CASE 80 

7050 DISP "Door open -- shut it and press C0NT" 

7 0 B 0 PAUSE 

7080 CASE 83 

7090 DISP "Write protected -- fix and press CDNT" 

7100 PAUSE 

7120 CASE 85 

7130 DISP "Disc not initialized -- fix and press C0NT 

7140 PAUSE 

71B0 CASE 56 

7170 DISP "Creating Data_file" 

7180 CREATE BDAT "Data_fi1e"#20 

7190 CASE ELSE 

7200 DISP "Unexpected error "5ERRN 

7210 PAUSE 

7220 SUBEND 
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ON ERROR RECOVER 

The ON ERROR RECOVER statement sets up an immediate branch to the specified line 
whenever an error occurs. The line specified must be in the context of the ON...RECOVER 
statement. ON ERROR RECOVER is global in scope — it is active not only in the environment 
in which it is defined, but also in any subprograms called by the segment in which it is defined. 

If an error is encountered while an ON ERROR RECOVER statement is active, the system will 
restore the context of the program segment which actually set up the branch, including its 
system priority, and will resume execution at the given line. 


3250 DN ERROR RECOMER Give_up 
32B0 CALL Mode1_uniuerse 
3270 DISP "Successfully completed" 
3280 STOP 

3290 Give-up: DISP "Failure 
3300 END 


5ERRN 
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Chapter 

12 


Introduction 

The problem of debugging a program is distinct from the issues raised in Chapter 11, Error 
Handling. Chapter 11 is based on the premise that the programmer is satisfied that the program 
works as it should, and that it then should be made as foolproof as possible. This could be 
construed as putting the cart before the horse — before you can make a program foolproof, you 
must get it to run correctly in the first place. One of the key characteristics of a “bug” is that it 
doesn’t necessarily have to cause an error condition to occur — it only has to cause your program 
to give a wrong answer. This chapter deals with the methods available on this computer to diagnose 
problems in logic and semantics. 

Naturally, the ideal way to debug a program is to write it correctly the first time through, and all 
programmers should strive constantly to achieve this state of nirvana. Hopefully, the techniques 
that have been been discussed in this manual will help you get a little closer to this goal. The 
practice of writing self documenting code and designing programs in a top down fashion should 
help immensely. 

Aside from recommended methods of writing software, the computer itself has several features 
which aid in the process of debugging. 
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Using Live Keyboard 

One of the pleasing characteristics of this computer is that its keyboard is “live” even during 
program execution. That is, you can issue commands to the computer while it is running a program 
the same way that you issue commands to it while it is idle. For instance, you can add two numbers 
together, examine the catalogue of the disc currently installed in the drive, list the running program 
to a printer, scroll the CRT alpha buffer up and down, enter and exit either the graphics or alpha 
displays, or output a command to a function generator over HP-IB. Practically the only thing you 
can’t do from live keyboard while a program is running is write or modify program lines, or attempt 
to alter the control structures of the program. (A complete list of illegal keyboard operations is given 
a little later on.) 

By way of illustration, key in the following program, press ( RUN ) , and then execute the commands 
shown underneath the listing. 

10 FOR 1=1 TO l.E+5 

20 NEXT I 

30 END 

CAT 
2 + 2 

9QR(G"2+17.2 A 2) 

PRINT "THE QUICK BROWN FOX" 

TIMEDATE 

Now, this program will take a fair amount of time to complete (about 18 seconds), so to find out 
how far the program has gone, merely type I and press ( EXECUTE ) or ( RETURN ) . The current value 
of 1 will be displayed at the bottom of the screen. Now if you don’t want to wait for the program to 
go through all one hundred thousand iterations, you can merely change the value of I by executing 
the command 

1=99999 


Thus, we have seen that live keyboard can be used to examine and/or change the contents of the 
program’s variables. 

One aspect of live keyboard to be aware of is that the computer will only recognize variables that 
exist in the current program environment. For instance, suppose that we change our example 
program to call a subprogram inside the loop. 


10 

FOR 1=1 TO 

1 ♦ 

15 

CALL Dummy 

20 

NEXT I 


30 

END 


40 

SUB Dummy 


50 

FOR J=1 TO 

10 

GO 

NEXT J 


70 

SUBEND 



While this program is running and you test the variable I from the keyboard, chances are that you 
will only get a message saying that I doesn’t exist in the current context — most of the time will be 
spent in the subprogram. On the other hand, if you test the value of J, it is highly likely that you will 
get an answer. 
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Similarly, operations like ASSIGN and ALLOCATE, which are declarative types of statements, 
must use variables that are already known to the current environment when they are executed from 
the keyboard. For example, in the following program, it is perfectly legal to perform the operation 
ASSIGN @Dvm TO * from the keyboard, although it is not legal to perform 
ASSIGN ©File TO " DATA " from the keyboard. 

1 ASSIGN @Dv m TO 724 

10 FOR 1=1 TO l.E + 5 

20 NEXT I 

30 END 

Live keyboard operations are allowed to use variables already known by the running program. Live 
keyboard operations are not allowed to create variables. 

Although the GOTO and GOSUB commands are illegal from the keyboard, it is perfectly legal to 
call subprograms from the keyboard. The only restriction on using SUB and function subprograms 
from the keyboard is that the parameters that are passed must either be constants or must be 
variables that exist in the current context. 


Here is an example: 

10 FOR 1=1 TO l.E+5 

20 NEXT I 

30 END 

31 ! 

40 SUB Gather(INTEGER X) 

50 OPTION BASE 1 

GO DIM A(32) 

70 CREATE BDAT " F i 1 e " 0AL$ ( X ) »1 
80 ASSIGN @Dum TO 724 

SO ASSIGN @Fi1e TO "File"&MAL$(X) 

100 OUTPUT @Dvm 5"N100S" 

110 ENTER @Dvm 5 A(#) 

120 OUTPUT @Fi1e5A<*) 

130 PRINT A<*> * 

140 SUBEND 

141 ! 

150 DEF FNPoly(X) 

1G0 RETURN X"3 + 3*X A 2 + 3*X + X 
170 FNEND 


By executing CALL Gather(l) from the keyboard, the main program will be suspended while the 
subprogram is called, at which time a 1 record file will be opened, 32 readings will be taken from 
the voltmeter and stored in the file, and the readings will be printed on the screen. Then main 
program execution will resume where it left off. 

Similarly, by typing FNPoly(l), the value of the polynomial will be computed for X=1 and the 
answer (8) will be displayed at the bottom of the screen. 


Here is a list of commands which may not be executed from the keyboard while a program is 
running, although they may be executed from the keyboard if the computer is idle: 


RUN 

SCRATCH 

GET 

CONT 

SCRATCH A 

LOAD 

EDIT 

SCRATCH C 

LOAD BIN 

DEL 

SCRATCH BIN 

SYSBOOT 
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Stepping 

One of the most powerful debugging tools available is the capability of single stepping a program, 
one line at a time. This process allows the programmer to examine the values of his variables and 
the sequence in which the program is running at each statement. This is done with the ( STEP ) key. 

There are three ways to use the ( STEP ) key: 

1. If the program is stopped (i.e., a prerun has to be performed), pressing the ( STEP ) key will 
cause the system to perform a prerun on the program, but no program lines will actually be 
executed. The first line that will be execu ted will appear in the system message line at the 
bottom of the screen. Pressing the ( STEP ) key again will cause that line to be executed, and 
the next line after that to be executed will appear in the message line. If the ( STEP ) key is 
pressed causing the next line to appear in the display, and a live keyboard operation (such as 
examining th e value of a variable) is performed, the contents of the message line will change. 
Pressing the ( STEP ) key again will still cause the line to be executed, even though it is no 
longer visible in the implied display line. After the statement has completed, the next line will 
again appear. 

2. If the program is in an INPUT or LINPUT statement, pressing the ( STEP ) key is sufficient to 
terminate the operation. Any data ente red fro m the keyboard will be entered into the correct 
variables, just as though ( CONTINUE ) or ( ENTER ) had been pressed, but program execution will 
be PAUSEd, and the statement immediately following the INPUT or LINPUT will appear in 
the system message line. 

3. If the program is in a PAUSEd state, pressing the ( STEP ) key will cause the next line to be 
executed. The program counter will not be reset, nor will a prerun be performed. Again, the 
next line to be executed will appear in the system message line after the last one has been 
completed. A paused state is indicated by a dash in the run light in the lower right hand 
corner of the screen. 

Type in the following example and execute it by pressing the ( STEP ) key repeatedly. 

10 DIM A(1:5) 

20 ! This is an example 

30 S = 0 

40 FOR 1=1 TO 5 

50 INPUT "Enter a number"»A(I) 

GO S=S+A(I) 

70 NEXT I 

80 PRINT S 

30 PRINT A(*) ! 

100 END 


Notice that the ( STEP ) key caused every statement to appear in the system message line, one at a 
time, even those statements that are not really executed, like DIM and comments. 






























Program Debugging 311 


Tracing 

The process of single stepping, wonderful though it is, can be quite slow, especially if the pro¬ 
grammer has little or no idea which part of his program is causing the bug. An alternative way of 
examining variable changes and program flow is available in the form of the TRACE ALL state¬ 
ment. 

TRACE ALL 

When the TRACE ALL command is executed, it causes the system to issue a message prior to 
executing every line (this shows the order in which the statements were executed), and if the 
statement caused any variables to change value, a message telling the variables involved and their 
new values is also issued. The messages are issued to the system message lin e, and the most useful 
way to use the TRACE ALL feature is to turn Print All On (use the ( PRT ALL ) key), unless of course 
you’re a very fast reader. (The printall mode will cause all information from the DISP line, the 
keyboard input line, and the system message line to be logged on the PRINTALL IS device.) 

Turn Print All ON and key in the following example to see how TRACE ALL works: 


10 

TRACE ALL 


20 

FOR 1=1 TO 10 


30 

PRINT 15 


40 

IF I MOD 2 THEN 


50 

PRINT " is 

odd* n 

GO 

ELSE 


70 

PRINT " is 

e v e n ♦ 

80 

END IF 


90 

NEXT I 


1 0 0 

END 



There are two optional parameters that can be used with TRACE ALL. Both parameters are line 
identifiers (line numbers or line labels). The first parameter tells the system when to start tracing, 
and the second one (if it’s specified) tells the system when to stop tracing. The following example 
illustrates the use of one optional line specifier: 


1 

TRACE ALL 40 

10 

DIM A( 1 

: 10) 


20 

FOR 1=1 

TO 

100 

30 

NEXT I 



40 

FOR J=1 

TO 

10 

50 

A ( J ) = J 



GO 

NEXT J 



70 

END 




It is usually more useful to use the TRACE ALL command from the keyboard rather than from the 
program because a program modification is not necessary if you want to trace a different part of the 
program. All that’s necessary is to type in a new TRACE ALL command from the keyboard to 
override the old one. In the above example, to trace the loop from 20 to 30 instead of the one from 
40 to 60, simply delete line 1 and type in TRACE ALL 20 >40 from the keyboard. 
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10 

DIM 

A ( 1 

5 1 0 ) 


20 

FOR 

1 = 1 

TO 

100 

30 

NEXT 

I 



40 

FOR 

J=1 

TO 

10 

50 

A( J) 

= J 



GO 

NEXT 

J 



70 

END 





The program will begin tracing at line 20, and keep on tracing until it’s ready to execute line 40, at 
which time it will terminate the trace messages and will continue executing the program normally. 

If the TRACE ALL statement uses a line label instead of a line number, be aware of what happens if 
you have more than one occurence of a given line label in your program. For instance, it is perfectly 
legal to have the same line label in two or more different program environments — line labels are 
local to subprograms and branching operations addressing a given line label are treated separately 
in different subprograms. However, when a TRACE ALL using a line label is executed, the first line 
label in memory is the one that gets used, regardless of the environment the progam was in when 
the TRACE ALL statement was executed. Thus in the following program, even though the TRACE 
ALL Printout statement is executed inside the subprogram, tracing does not commence until the 
subprogram has been exited and the Printout statement in the main program has been executed. 

10 DIM A(1:10) 

20 FOR 1=1 TD 10 

30 CALL Dummy(A(*) »I) 

40 G0SUB Printout 

50 NEXT I 

GO STOP 

70 Printout: ! 

80 FDR J=1 TO 10 

90 PRINT A(J) i " >“5 
100 NEXT J 

105 PRINT 

110 RETURN 

120 END 

130 SUB Dummy<X(*> »Z> 

140 TRACE ALL Printout 

150 FOR 1=1 TO 10 

1 GO X(I)=2*100+1 

170 NEXT I 

180 G0GUB Printout 

180 SUBEXIT 

200 Printout: ! 

210 PRINT "D u m my routine exec u ted"52 
220 RETURN 

230 SUBEND 

If two line identifiers are used, their location with respect to each other does not matter. Tracing will 
start when the line specified first is encountered, and it will stop when (or if) the second line is 
encountered. 
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PRINTALL IS 

The PRINTALL IS command is useful for switching the tracing messages between the CRT and a 
hardcopy printer. (Again, to get any record at all of the trace messages, Print All must be On.) To 
cause the trace messages to be logged on the CRT, execute PRINTALL IS CRT. (The CRT is the 
default PRINTALL IS device that the system assumes when it wakes up.) To cause the messages to 
be logged on a printer, merely change the device selector to the appropriate value (PRINTALL IS 
701). 

TRACE PAUSE 

The TRACE PAUSE command can be used to set a “break point” in the program. The program 
will execute at a reduced speed until the specified line is reached, at which time the program will 
pause, and the specified line will be shown in the implied display line, indicating that the program 
will ex ecute it when execution is resumed. Execution may be resumed with the ( CONTINUE ) key, the 
( STEP ) key (which will only cause one line to be executed), or by executing CONT from the 
keyboard (the specified line identifier must be located in the current environment). 

By executing the command TRACE PAUSE Printout from the keyboard, the following program will 
pause every time it reaches line 70. 

10 DIM A(1:10) 

20 FOR 1=1 TO 10 
40 G0SUB Printout 

50 NEXT I 
B0 STOP 
70 Printouts ! 

80 FOR J=1 TO 10 
80 PRINT A ( J ) 5" » " 5 
100 NEXT J 
110 PRINT 
120 RETURN 
130 END 

Try the following ways of continuing execution: 

press ( STEP) 
press ( CONTINUE ) 
execute CONT 110 

As with TRACE ALL, a new TRACE PAUSE statement overrides a previous one. The same rules 
are applied when a line label is used in a TRACE PAUSE statement as are applied to the TRACE 
ALL statement — the first line in memory having that label is used. 

TRACE OFF 

TRACE OFF cancels the effects of any active TRACE ALL or TRACE PAUSE statements. The 
status of Print All and the PRINTALL IS device will be unchanged. 

TRACE OFF may be executed either from the program, or from the keyboard. 
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The CLR I/O Key 

The (CLR I/O) key ( (BREAK) on HP 46020A keyboards) suspends any active I/ O operatio n an d paus es 
the program in such a way that the suspended statement will restart once ( CONTINUE ) or ( STEP ) is 
pressed. This is useful for operations which appear to “hang” the machine, such as printing to a 
printer which isn’t turned on. 


Most devices will not respond to ENTER requests unless they have first been ins tructed to respond. 
If improper values are sent to a device, it may refuse to respond. Therefore, (CLR I/O) can help in 
debugging these situations. 


Here are the operations that can be suspended with (CLR I/O) . 


PRINT 

LIST 

CAT 

OUTPUT 

DUMP GRAPHICS 
DUMP ALPHA 


SEND 

PRINTALL outputs 

ENTER 

INPUT 

HP-IB commands 
External plotter commands 


ASSIGN 

PURGE 

CREATE 

Some graphics commands 
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Chapter 

13 


Introduction 

Every model of computer has certain characteristics which can result in better performance, pro¬ 
vided the programmer knows what those characteristics are and how he can take advantage of 
them. This chapter consists of a potpourri of such items. 


Data Storage 


Data Storage in Read/Write Memory 

There are four data types on this computer: REAL, INTEGER, strings, and I/O path names. The 
R/W memory occupied by data is made up of two parts: the memory it actually takes to hold the 
intended information, and the memory that the system uses to keep track of the information’s 
location and form (this is called overhead). Strings, INTEGERS, and REALs can be declared either 
as simple variables or as arrays. Arrays take different amounts of overhead than simple variables, 
but each element of an array uses the same amount of memory that a corresponding simple 
variable uses to actually store information. 

The overhead required for any given symbol is kept in three tables: the symbol table, the token 
table and the dimension table. The symbol table contains pointers to the value area, where the 
actual information is kept, and to the other two tables. The token table contains the names of the 
various symbols. The dimension table contains length information for strings and arrays, and is not 
used for numeric scalers. The tables are not constructed in single units as symbols are added and 
deleted. Rather, as new space is required, the system will first look to see if there are any unused 
entries in the tables — if new space is allocated, usually enough for several entries is allocated. For 
instance, the symbol table is built in increments of five entries. 


Symbol Table Overhead: 
Token Table Overhead: 


Dimension Table Overhead: 


10 bytes per symbol 

number of characters in the name + 1 (if the above number is 
odd, it is rounded up to an even number). Note that the name for 
I/O path names, strings, and functions includes the $, and FN, 
respectively. 

For arrays: 3 bytes (total size) 

1 byte (number of dimensions) 

4 bytes for each dimension (for the lower bound, 
and the size of each dimension) 

For strings: 2 bytes (maximum length) 

For string arrays — all of the normal array overhead, plus two 
bytes for the maximum allowed length of an element 
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Note that line labels, COM labels, and subprograms are considered as symbols, and occupy space 
in both the symbol and token tables. Line numbers used in statements, like GOTO 20, also occupy 
space in the symbol table. 

Every subprogram (or context) has its own set of tables. In addition, there is a global set of COM 
tables, where all information concerning COM blocks is kept. Symbols that belong to a COM block 
will occur in both the COM tables and in any local tables in which that COM block is declared. Since 
each context may define the names by which it refers to COM block variables, there will be no entry 
in the COM token table for each variable, but an entry in the COM token table will occur for COM 
labels. 

ALLOCATEd variables require four bytes of overhead in addition to the overhead already discus¬ 
sed for the symbol, token, and dimension tables. 

The following table summarizes the storage requirements for various data types. This table does not 
show the extra requirements just mentioned for ALLOCATEd and COM variables. 


Type 

Overhead 

Information Storage 

Simple INTEGER 

10 bytes 4- name overhead 

2 bytes 

Simple REAL 

10 bytes + name overhead 

8 bytes 

Simple string 

12 bytes + name overhead 

1 byte per char, up to declared length (padded 
to even number of chars.) + 2 bytes (length 
information) 

I/O path name 

10 bytes + name overhead 

100 bytes 

INTEGER array 

14 bytes + name overhead 
+ 4 bytes per dimension 

2 bytes per element 

REAL array 

14 bytes + name overhead 
+ 4 bytes per dimension 

8 bytes per element 

String array 

16 bytes + name overhead 
+ 4 bytes per dimension 

1 byte per char, up to declared length (padded 
to even number of chars.) + 2 bytes (length 
information) per element 


Data Storage on Mass Memory Devices 

The amount of storage that data takes on mass storage media is similar to the amount of RAV 
memory that data takes internally, except that no overhead is required (on BDAT files). Arrays and 
single values are interchangeable on mass storage — no distinguishing information is kept on the 
media. 


INTEGERS (and INTEGER arrays) 2 bytes (per element) 
REALs (and REAL arrays) 8 bytes (per element) 

Strings (and string arrays) 4 bytes + 1 byte per char 

up to current length, pad¬ 
ded to even number of 
chars, (per element) 
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For ASCII files, all information is converted to string (or ASCII) form, and a two-byte length field is 
tacked onto the front of every field. 

INTEGERS (and INTEGER arrays) 2 bytes + 1 byte per digit (per element) 

REALs (and REAL arrays) 2 bytes + 1 byte per digit (per element) 

Strings (and string arrays) 2 bytes + 1 byte per char (per element) 

Comments and Multicharacter Identifiers 

Self-documenting features such as in-line comments and multicharacter variables and line labels 
are useful because of the benefits to be reaped in terms of developing, testing, debugging, and 
maintaining programs. They do take extra memory, but this shouldn’t be a problem if you keep the 
following points in mind. 

Comments take 1 byte of R/W memory for every character in the comment. If memory space 
becomes a problem, many people resort to keeping two copies of their programs around — one 
fully commented to use as reference material, and the other uncommented to use as the “produc¬ 
tion version”, which is the one that is actually used. 

Multicharacter identifiers are only spelled out in their entirety once — not every time they are used. 
The program actually stores pointers whenever a reference to the identifier is used, so using short 
identifiers won’t result in any appreciable savings in memory used. 

Variable and Array Initialization 

Care should be taken to initialize any variables before using them in an expression (on the right 
hand side of an =, as a left-hand subscript in a function or subprogram parameter list, as an 
argument to a built-in function, or in a PRINT/OUTPUT/DISP list). The system will set variables to 
zero, strings to null, and I/O path names to undefined at program prerun, but depending upon 
defaults like this is considered bad programming practice and could lead to subtle errors. For 
instance, the first time a certain line is executed, the variables used may be assumed to be zero 
because of the prerun operations. Once this assumption has been made, the danger is that the 
programmer will branch back to the same section of code and forget that the zeroing process has 
not been performed — an error may result that didn’t occur previously. 
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Mass Memory Performance 


Program Files 

There are two ways to store programs — they can be saved either as ASCII source strings using the 
SAVE command, or they can be stored in an intermediate form that the BASIC language system 
understands using the STORE command. 

If the time it takes to load the program is important, always use the STORE command to store the 
program instead of the SAVE command. The LOAD command, which reads in files created by the 
STORE command, will execute about fifty times faster than the GET command. This is because the 
LOAD command does not require that the information on the file be processed in any way. Since 
the program is already in the form the system needs it in, all that is necessary is to funnel the 
program directly into memory as fast as the disc can spin (assuming an interleave of one). 

SAVE files, on the other hand, require that the system parse and check the lines as they are read, 
just the same as if a user had typed them in from the keyboard. Consequently, the speed at which 
the program gets loaded into memory with the GET command will be drastically slower than the 
LOAD command. Using the Models 226 and 236 internal drives as an example of the relative 
speeds, a typical 8K byte program will take about 30 seconds to GET, but only about one second to 
LOAD. 

One advantage of the GET/SAVE commands is that it is possible to deal with programs as string 
data. 

Data Files 

As with program files, there are two types of data files: ASCII and BDAT. ASCII files require that all 
data be in string form, while BDAT files are interpreted as internal data representations. 

When reading or writing data to an ASCII file, the number formatter is required to convert the data 
in between its internal representation and its ASCII form. When reading or writing data to a BDAT 
file the data may stream directly back and forth with no conversion required. Using the Models 226 
and 236 internal drives as an example, an 8K element REAL array (64K bytes) may take around 
200 seconds to write in an ASCII file, while the same array will only take about 5 seconds to write to 
a BDAT file. 

The primary benefit of the ASCII data file is the transportation of data between different models of 
Hewlett-Packard computers and terminals and between discs used with different language systems. 






Efficient Use of the Computer’s Resources 319 


Benchmarking Techniques 

This section discusses the techniques used to determine how fast various operations execute. 
Ideally, you should separate the measurement time from elapsed time: 

10 T1=TIMEDATE 
20 T2=TIMEDATE 

30 PRINT T1-T25“seconds used to read clock" 

40 END 

In actuality, the clock only has a resolution of 10 ms, so you won’t usually be able to time this 
operation. 

Next, most operations are performed inside a loop in order to be able to time operations that are 
faster than the resolution of the clock (clock resolution is 10 ms.). This also tends to “smooth out” 
varying system overhead characteristics. 

10 INTEGER I 

20 T1=TIMEDATE 
30 FOR 1=1 TO 10000 

40 NEXT I 

50 T2=TIMEDATE 

GO PRINT T2-T1 5"seconds of loop overhead" 

70 END 

A certain amount of time used in computational operations will involve moving information around. 
The time will be different depending upon the type of the information being moved (string, REAL, 
or INTEGER), and for strings, the length. 

10 REAL A *5fC 

20 INTEGER I 

30 B = PI 

40 T1=TIMEDATE 
50 FDR 1=1 TO 10000 

GO A = B 

70 NEXT I 

80 T2=TIMEDATE 

90 PRINT T2-T15"seconds of loop overhead" 

100 END 
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The next step is to actually time the operation of interest. It should be noted that for arithmetic 
operations, the time spent performing the operation will vary depending upon the two operands 
(number of digits and relative magnitudes). 


10 REAL A >B >C 
20 INTEGER I 
30 B=PI*l.E+53 

40 C=EXP(SQR<2)"13.81 > 

50 PRINT "B="5B»"C=" iC 

B0 T1 =T IHEDATE 

70 FOR 1=1 TO 10000 

80 A = B 

90 NEXT I 

100 T2 = T IMEDATE 

110 FOR 1=1 TO 10000 

120 A=B+C 

130 NEXT I 

140 T3=TIMEDATE 

150 0p_time=DR0UND(T3-T2-T2+Tl»3> 

1B0 PRINT Dp_time*100 !"us. per operation 
170 END 


The above program will show anywhere from 148 to 150 microseconds per operation for addition. 
Here is a list of a few other operations: 


Addition 

150 

|JIS 

Subtraction 

165 

(JLS 

Multiplication 

301 

|XS 

Division 

460 

|JLS 

Exponentiation 

7590 

|XS 


These times vary for different processor boards. Use these times and others throughout this chapter 
to compare the speeds of different operations. 
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INTEGER Variables 

We have seen in the first section of this chapter that INTEGER variables don’t take as much 
memory as REAL variables (2 bytes instead of 8). Now we shall discover that some operations with 
INTEGERS are much faster than the same operations with REALs. 

Minimum and Maximum Values 

The INTEGER variable type may store any whole number from -32 768 to +32 767 inclusive. 

Mathematical Operations 

There are two sets of math routines provided for the MOD, DIV, +, —, and * * operations: REAL 
and INTEGER. Depending upon the types of the operands used, the execution times for these 
operations will vary widely. The tradeoffs are: 

INTEGER math is the faster of the two, since it doesn’t require as much “work”. This is because: 

1. There are only two bytes of data to process instead of eight 

2. Operations do not have to deal with a combination of mantissa and exponent. 

3. The results don’t have to be normalized. 

4. INTEGER math can be done directly in the hardware. 

REAL math, though slower, is generally more widely used because it allows numbers with fractional 
parts to be analyzed. REAL numbers carry about 16 decimal digits of precision and have an 
exponent range of - 308 to + 308. 


Note 

All times specified are without the floating point card. If you have this 
card, your times will be faster for REAL math. 


For instance, suppose you want to compute your monthly pay. Assume that you’re making $5.17 
an hour, that you work twenty four days per month and that you work 14 hours per day. The 
calculation that you would use is 5.17*24*14 or $1737.12. In this problem, you definitely want 
your computer to use REAL precision math (or you’ll lose 17 cents per hour!) even though you’re 
only using 6 of the 16 digits available. 

The computer will pick whatever math routines it needs to solve the current problem. However, the 
programmer can exercise control over which math routines get executed if the following rules are 
understood. 

• INTEGER math is used if both arguments of a MOD, DIV, *, +, or -operation are of type 
INTEGER. If the results of the operation cannot be stored in an INTEGER, then an error is 
generated (INTEGER overflow). 

• REAL math is used if either or both arguments of a MOD, DIV, *, +, or - operation is of type 
REAL. If one of the arguments is of type INTEGER, then that argument is first converted to 
REAL. 

• REAL math is always used for exponentiation and division (slash). 
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The following table gives some approximate time comparisons between INTEGER and REAL 
operations for +, and *. The times are approximations because REAL math routines do 
different things depending upon the values of the operands. All times shown here were found on 
operations with numbers having no fractional parts. The multiplication times were found for oper¬ 
ands in the range of — 200 to + 200. 


REAL INTEGER 


MOD 

DIV 

Addition 

Subtraction 

Multiplication 


160 |xs 91 (as 

352 (as 88 |xs 

142 (jls 68 (jls 

174 (as 68 |as 

152 (as 77.113s 


Multiplication, like most math operations, will execute faster on INTEGER values. However, bear in 
mind that it’s much easier to get an INTEGER overflow on multiplications than on additions and 
subtractions. For instance, 200*200 will give an INTEGER overflow. If you are performing multi¬ 
plication on INTEGERS, you should carefully examine your program to ensure that the range of 
your answers doesn’t force you to use REALs, even if the requirement for fractional precision 
doesn’t. 


Loops 


In general, any FOR/NEXT loop using an index which has been declared to be an INTEGER will 
execute about 2.4 times faster than a loop whose loop counter is a REAL. Type in the two 
programs below and run them to see the difference. 

10 REAL I 

20 T0=TIMEDATE 
30 FOR 1=1 TO 10000 

40 NEXT I 

50 PRINT TIMEDATE-T05"seconds" 

B0 END 

Time is about 1.67 seconds. 

10 INTEGER I 
20 T0=TIMEDATE 
30 FOR 1=1 TO 10000 

40 NEXT I 

50 PRINT TI MEDATE-TO 5"seconds" 

GO END 

Time is about .69 seconds. 

Bear in mind that the 2.4 speed improvement is only on the time devoted to actually incrementing 
and testing the loop variable (in these examples, I). So, any loop that iterates for 10 000 times will 
run about a second faster if the index is an INTEGER instead of a REAL. Now, saving a second on a 
loop that executes 10 000 times may not sound like much by itself, and it’s not. But what if that 
loop is nested inside another one that executes 10 000 times? Now your time savings is 10 000 
seconds, or two hours and forty-five minutes! Just for declaring the loop counters to be INTEGER. 
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Naturally, making a loop index into an INTEGER will only work if the loop is not stepping in 
fractions, and if the minimum and maximum values of the loop index do not exceed the range of 
-32 768 thru +32 767. 

Array Indexing 

Accessing individual array elements is faster if the variables or expressions giving the indices into the 
array are INTEGER instead of REAL. This is because the system has to convert floating point 
numbers into an INTEGER in order to find the offset from the beginning of the array. If the index is 
already in INTEGER form, the conversion isn’t necessary. The following example illustrates this 
point. 

10 REAL I 

20 DIM A(l:1000) 

30 X=17.508 
40 T0=TIMEDATE 

50 FDR 1=1 TO 1000 

00 A(I)=X 

70 NEXT I 

80 PRINT TIMEDATE-TOi"seconds" 

90 END 

10 INTEGER I 

20 DIM A(1:1000) 

30 X=17.588 
40 T0=TIMEDATE 
50 FDR 1=1 TO 1000 

GO A(I)=X 

70 NEXT I 

80 PRINT TIMEDATE-TO 5"seconds" 

90 END 

You will find a difference of . 14 seconds between the two programs’ execution times, due to a 
combination of the loop counter being INTEGER and the INTEGER indexing of the array. Again, if 
you’re operating on a much larger array, or if you’re working on a multi-dimensional array this 
number can become noticeable. 
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REAL Numbers 


Minimum and Maximum Values 

The minimum REAL number that can be stored on this computer is approximately 
±2.225 073 858 507 202 x 1CH 08 

The maximum REAL number that can be stored on this computer is approximately 
± 1.797 693 134 862 315 x 10 308 


A REAL number can also have the value zero. 


Type Conversions 

Earlier, it was mentioned that any time a MOD, DIV, *, +, or -operation is performed on two 
numbers of different type (one INTEGER, and one REAL), a type conversion has to take place to 
convert the INTEGER to a REAL. This section will address other situations where type conversions 
have to take place. 


Any time an INTEGER is used in an exponentiation or division operation, it must first be converted 
to a REAL. 


All of the following functions require a REAL argument (with the exception of VAL and RND), and 
all of them return a REAL value (with the exception of RANDOMIZE). If an INTEGER is passed in, 
or if the result is to be stored in an INTEGER, then the appropriate type conversion must be made' 
EXP, LGT, LOG, RANDOMIZE, SQR, DROUND, RND, ACS, COS, ASN, SIN, ATN, TAN, VAL. 

All of the comparison operators ( =,<>,<,>,< = ,>= ) will return INTEGER values (0 or 1) 
but will accept either INTEGERS or REALs as arguments. The logical operators AND, EXOR, OR, 
and NOT will convert any arguments to the INTEGER values 0 or 1 before the operation is 
performed, and an INTEGER 0 or 1 will be returned. 

The binary bit functions (BINAND, SHIFT, ROTATE, BINIOR, BINCMP, BIT, BINEOR) require 
INTEGER inputs and provide INTEGER outputs. Type conversions will be performed if REALs are 
supplied as inputs, or if the results are to be stored in a REAL variable. 

SGN returns an INTEGER (-1, 0, 1) regardless of the type of the argument passed to it. ABS and 
INT return the type of the argument that’s passed to them. 

If two INTEGERS are used to perform a MOD, DIV, *, +, or -operation, but the result is to be 
stored in a REAL variable instead of an INTEGER, then the result must be converted from 
INTEGER to REAL. 

Here is how long each type conversion takes: 

INTEGER to REAL: 42 microseconds 
REAL to INTEGER: 34 microseconds 
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Constants 

All constants that are within the range of — 32 767 to 32 767 that aren’t entered with a decimal 
point or an “E” (for scientific notation) are stored in the machine as INTEGERS. Integer constants 
should always be used with INTEGER variables, but if they are used with REAL variables they will 
have to be converted to REAL first. This operation will slow down the execution of the program, as 
shown in the previous section. Any numbers entered with decimal points (1.0, 3., .7, etc.), with an 
E (IE-304, .2E48, 0E0, etc.), or outside the valid INTEGER range (40000, -75986, etc.) will be 
stored as REAL constants. 

Polynomial Evaluations 

The polynomial can waste much of computer time because programmers tend to pick the most 
obvious, and also the most time-consuming, method of evaluating them. Polynomials are usually 
written mathematically as: 

y = a n x n + a n _!X n-1 + ... + a x x + a 0 
or 


n 



hence the temptation is strong to evaluate a polynomial on a computer as: 

2000 DEF FNPoly(X^Coefficient(*) ^INTEGER N) 

2010 INTEGER I 
2020 Y = 0 

2030 FOR 1=0 TO N 

2040 Y = Y + Coef f icier, t ( I )*(><" I ) 

2050 NEXT I 
2060 RETURN Y 
2070 FNEND 

In the above program, there are N +1 additions, N + 1 multiplies, N +1 exponentiations, and N +1 
INTEGER to REAL conversions (I is converted to a REAL when the exponentiation operation is 
performed). Now suppose the polynomial is written in the equivalent form: 
y = a 0 + x(a x + x(a 2 + ... + x(a n )... ) ) 


Then the corresponding program would be: 

2000 DEF FNPoly(X^Coefficient<*) ^INTEGER N) 

2010 INTEGER I 

2020 Y=Coefficient(N) 

2030 FOR I = N-1 TO 0 STEP -1 
2040 Y = Coef f icier, t ( I )+X*Y 
2050 NEXT I 
2060 RETURN Y 
2070 FNEND 

Now there are only N additions and N multiplies, and NO exponentiations or INTEGER to REAL 
conversions! The following chart shows the time savings as a function of the order of the polyno¬ 
mial. For example, if the polynomial is of order 10, it is 70 milliseconds faster to use the nested 
multiply method to evaluate the polynomial than to use exponentiation. If you’re plotting a 
thousand points on a graph, nested multiplication will save you more than a minute! 
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DIFFERENCE BETWEEN NESTED MULTIPLICATION 



Logical Comparisons for Equality on REAL Numbers 

Don’t do it. 

If you are performing mathematical operations on REAL numbers, and then comparing them for 
equality, the chances are that they will never come up equal. For example, in the previous section 
on polynomial evaluation, you can pass the same value for X and the same coefficient array to each 
of the two functions, and although the results will look equal when you print them out, they won’t 
show equality if you compare them. ( Try it and see.) A shorter example is to type out this 
expression from the keyboard and press ( EXECUTE ) : 

• 1 + ♦1 + #1 + ♦1 + •1 + ♦1 + •1 = ♦ 7 

The 0 at the bottom of the screen means that the machine doesn’t consider the two numbers to be 
equal. This is characteristic of the way that binary math works. 

Any REAL numbers should be rounded first before being tested for equality. This is one of the 
purposes of the DROUND function. 

DROUND(.l+.l+.l+.l+.l+.l+.l >12)=DROUND(.7 >12) 

After rounding both numbers to 12 digits, the computer will now accept them as being equal. See 
Chapter 4 for more discussion on the comparison of REAL numbers. 
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Saving Time 


Multiply vs. Add 

It is always faster to add a number to itself than it is to multiply it by 2. For instance, to perform 2*PI 
a thousand times takes .22 seconds, while to perform PI + PI a thousand times takes . 13 seconds. 

However, if you want to multiply by 3, that is faster than adding the number three times. 3*PI 
executed a thousand times takes about the same as 2*PI (.22 seconds), but adding PI + PI + PI a 
thousand times takes about .28 seconds. 

Exponentiation vs. Multiply and SQR 

Exponentiation is very slow when compared to other mathematical operations. The results are 
worth the wait when the exponent has a fractional part; raising a REAL number to a REAL power is 
a complex operation. However, time can be saved if you are alert to some special cases. The most 
common examples are squaring a number or finding a square root. Using SQR(X) takes only 
about one-fourth the time required by the expression X " . 5. Even more dramatic savings can be 
gained when raising numbers to an integer power. Using X*X yields a 22-to-l time savings over the 
expression X " 2. When using powers greater than 2 or 3, the expressions needed to achieve the 
repeated multiplication can be somewhat cumbersome, and may not even fit on a program line. 
However, repeated multiplication is so much faster than exponentiation that time savings can be 
realized (for powers up to 14) even if a FOR...NEXT loop has to be added to repeat the multiplica¬ 
tion. 

Array Fetches vs. Simple Variables 

It takes more time to access an array element than it does a simple variable. This is because the 
address of the array element has to be computed from the starting address of the array and the 
offset within the array based on the specified indices. A simple variable’s address does not require 
this computation. 

Thus, if you access a given array element often enough, especially within a loop, it will often be 
faster to store the array element into a simple variable and then operate on the simple variable. 

Time to fetch a simple variable and store it: 136 |xs 
Time to fetch an array variable and store it: 260 fxs 
Difference: 124 p,s 

This means that it is faster to fetch three simple variables than it is to fetch two array elements. 

Concatenation vs. Substring Placement 

The concatenation operator (&) allows you to combine two or more strings to construct another 
string. This operation is discussed in Chapter 5. However, there is a special case that can be 
accomplished faster without the concatenation operator. This is the case where the new string is 
built by appending to the end of an existing string. For example, A$ = A$B:B$. 
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Concatenation works by constructing a temporary workspace in which all the components are 
assembled. Then the result is moved to its destination. In the example above, A$ is moved to a 
temporary workspace, B$ is appended to it, and the result is moved back to A$. Thus, the original 
contents of A$, which weren’t changed, have been moved twice unnecessarily. A faster way to 
accomplish the same thing is: 

A$CLEN(A$)+1]=B$ 

Another benefit of this approach is that the temporary workspace is not created. If memory is tight 
and A$ is very large, concatenation could create a memory overflow. 

The following chart shows the time savings that result from using substring placement instead of 
concatenation. 
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Saving Memory 


The ALLOCATE and DEALLOCATE statements can be used to make efficient use of memory 
space in certain applications. They are useful in programs that contain a number of large 
variables that are not all needed simultaneously. For example: during data collection, a large 
string array is needed; during data processing a large numeric look-up table is needed; and 
during output formatting, a string array is needed again. Because a mass storage device is used 
to hold the data between processes, the same memory area can be used for all these arrays. 

To use ALLOCATE effectively, it is necessary to understand how the system reclaims areas that 
have been DEALLOCATED. Space for allocated variables is built using a stack discipline. The 
DEALLOCATE statement marks a space as unused. Unused space can be reclaimed only if it is 
the last space on the stack. There are two operations that use space in this stack. One is 
ALLOCATE, and the other is ON <event>. 

Keeping other allocated variables from blocking deallocated space is relatively simple. If you 
have only one allocated variable at any given time, this is not a problem. If you have allocated 
variables in existence simultaneously, ALLOCATE them in the opposite order of the DEALLO¬ 
CATE statements. Think of this in the same way you would think about nesting FOR...NEXT 
loops. 

Preventing blockage by ON conditions is more complicated. ON conditions, with one excep¬ 
tion, create control blocks that are permanent entries on the stack. As soon as you declare an 
ON (or OFF) condition, all the previous entries on the stack are “locked in” for the duration of 
the context and cannot be reclaimed. Therefore, all the control blocks should be created before 
any variables are allocated. Once a control block is created, it will be used by all subsequent ON 
and OFF statements that refer to the same resource. A good technique is to include an OFF 
statement for each desired event before allocating any variables. 

The exception mentioned above is an ON condition declared for an I/O path name. This 
includes ON END, ON EOT, and ON EOR. For these, subsequent ON and OFF statements 
behave as previously described. However, if the I/O path is closed, any control blocks associ¬ 
ated with the path are marked as unused. This has two implications. One, the reclaiming of the 
stack will not be blocked after the I/O path is closed. Two, you cannot force the system to leave 
these control blocks at the beginning of the stack. Here is an example: 

200 ASSIGN @Fi 1 e to "FRED" 

210 ON END @Fi 1 e GOTO Labell 

220 ALLOCATE Array(255t4) 


BOO ASSIGN @Fi 1e TO "SUSAN" 

BIO ON END @Fi 1 e GOTO Label2 
620 DEALLOCATE Array!*) 

At first, the array and control block are allocated in the proper order. The ASSIGN statement in 
line 600 closes the original path and opens a new path with the same name. When the ON END 
control block for the new path is created, it is placed after the array on the stack. Therefore, no 
memory space can be recovered by deallocating the array. 
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Notes 
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Graphics 


Chapter 

14 


Introduction 

Graphics is a powerful tool for presenting information. Computer graphics can be equally 
powerful but an extra step is required between the conception of the idea and the final image. 
This step is the construction of a mathematical model of the image within the computer. 

Since computers only do what they are told, it is essential to have a complete knowledge of the 
commands that communicate between the real world and the computer’s world. This know¬ 
ledge is needed to create the model within the computer’s memory and to understand the 
resulting image of the model. 

This chapter introduces basic graphics techniques. For more extensive information and examples, 
see the BASIC Graphics Techniques manual. 

A good place to start is the screen of the CRT. The screen serves a dual role; as an output device for 
text and as a plotting device for graphics. Although many applications require a plotter to produce 
the final image on paper, it is easier to develop the model on the screen. Then with minor changes 
the image can be sent to an external plotter. 

A non-bit mapped display is capable of displaying two rasters (images) either individually or 
combined. The alpha raster displays alpha-numeric characters while the graphics raster displays 
pixels (picture elements). The arrangement for the Model 216 and Model 226 is 400 columns of 
300 pixels; for the Model 236, 512 columns of 390 pixels. (Other monitors are available. The 
arrangement for all monitors is listed in the BASIC Language Reference manual in the GSTORE 
statement.) 

Display of the rasters is controlled by program statements (commands when executed im¬ 
mediately) or by keys located in the upper right corner of the keyboard. 

• Press [ GRAPHICS ) to turn on the graphics raster. A second press turns off the alpha raster. 

• Press (ALPHA) to turn on the alpha raster. A second press turns off the graphics raster. 

The rasters are also controlled by the BASIC statements: 

GRAPHICS ON and GRAPHICS OFF 
ALPHA ON and ALPHA OFF 

Initially the alpha raster is on and the graphics raster is off. During execution of a graphics 
program the alpha raster may be turned off but execution of an input statement turns the alpha 
raster back on and leaves it on. 

Bit mapped displays do not have a separate alpha and graphics raster. Both are combined and 
always on. 
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Graphics Fundamentals 

The First Step 

One statement initializes the system by setting default values. Several operations are actually 
performed by this statement. 

Execute the command. 

GINIT 

This statement (or its equivalent series of statements) should precede any other graphic state¬ 
ments. The system is now ready but nothing will be displayed until it is told to turn on the 
graphics raster. 

Either execute the command, 

GRAPHICS ON 
or press the ( GRAPHICS ) key once. 

Whenever you wish to clear the graphics raster, execute GCLEAR. GINIT also clears graphics raster 
but not until the execution of a graphics statement that selects a default plotter. 

If the alpha raster is not clear, press the ( CLR SCR ) key. 

Pencil and Paper 

Traditionally, a drawing requires pencil and paper. Here the paper is replaced by a display 
screen (CRT raster) and the pencil is replaced by the PEN statement. 

There are three currently defined pens for the monochrome graphics raster. 

PEN 1 turns pixels on. (white pen) 

PEN -1 turns pixels off. (black pen) 

PEN 0 complements pixels, (magic pen) 

When drawing with PEN 0, black pixels become white and white pixels become black. If you 
plan to send the image to an external plotter, do not expect a pen to erase a line. Check the 
plotter’s manual for different pen definitions. 

After selecting a pen, several statements, and their variations, control the motion of the pen on 
the drawing surface. 

DRAW X »Y draws a line to point X,Y. 

MOUE X t Y moves the pen to point X,Y. 

PLOT X »Y t P moves or draws to point X,Y. 

DRAW and MOVE do exactly what their names imply. PLOT will do both moves and draws 
with optional pen control. 
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Try the following. 

GINIT 

GRAPHICS ON 
DRAW GO.50 

A white line should appear from the lower left corner to the middle of the screen. Why the lower 
left corner? Executing the statement GINIT returns the pen to location 0,0. This is currently the 
lower left corner of the display. 

Execute the following commands to see their effect. 

GCLEAR 
PEN 1 
MOVE 0.50 
DRAW 100.50 
NOME 50.50 
PEN -1 
DRAW 0.50 
PEN 0 

DRAW 100.50 

A white line is drawn across the screen, the pen moved to the midpoint of the line, a black pen 
draws a line to the left endpoint, and the line is then complemented. 

To show the size of the current drawing area, the next statements draw a line around the 
perimeter, similar to the frame around a painting. 

GCLEAR 

PEN 1 

M0UE 0.0 

DRAW 100*RAT10 .0 

DRAW 100*RATI0>100 

DRAW 0.100 

DRAW 0.0 

There is a statement that duplicates the result of the previous example. Try the following. 

GCLEAR 

FRAME 

The Standard View 

The default scale for the Model 226 and Model 216 display is 133 horizontal units by 100 vertical 
units. For the Model 236 it is 131 horizontal by 100 vertical. For the Model 237 (HP 98781A 
display) it is 133 horizontal by 100 vertical. These units are called Graphic Display Units. The 
origin (location 0,0) is in the lower left corner of the graphics raster. The pen can be positioned 
anywhere, even outside the drawing area. You may wish to experiment some more to verify this. 
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Pen Control 

Pen action is automatically defined for the MOVE and DRAW statements. The pen is raised for 
a move and lowered for a draw. The PLOT statement has an optional pen control parameter 
that determines the pen’s action according to the following table. 


P value 

Result 

Odd 

Pen down 

Even 

Pen up 

Positive 

Change pen after motion 

Negative 

Change pen before motion 


The following example shows pen control by the optional pen control parameter. 


GCLEAR 


PLOT 20,20,1 


PLOT 40,20 

4 

PLOT 40,40,0 


PLOT 20,20,1 


PLOT 20,40 



Incremental Pen Positioning 

Often when plotting it does not matter where the pen has been, only the distance to the next 
desired pen position. 

I MOVE X >Y positive X moves pen to the right. 

negative X moves pen to the left. 

I DR AW X » Y positive Y moves pen up. 

negative Y moves pen down. 

I PLOT X , Y > P positive P changes pen after move. 

negative P changes pen before move. 

Execute the following and watch the results. 

GCLEAR 
MOVE 50 >50 
I DRAW 10»0 
I DRAW 0 #10 
I MOVE -10>0 
I DRAW 0,-10 

1 

With each incremental motion of the pen, a new origin is created for any subsequent in¬ 
cremental pen statement. A third method of moving and drawing involves specifying the 
relative movements of the pen from a local origin. 
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Relative Pen Positioning 

The relative plot statement uses the current pen position as a local origin to define a second 
coordinate system. Pen motion is then relative to the local origin until the pen position is 
changed by a statement other than another RPLOT statement. 

R P L 0 T X * Y * P where X and Y are relative displacemnts. 


Execute these commands to draw a triangle. 

GCLEAR 
MOUE 50*50 
RPLOT 20 *10 *-l 
RPLOT 20*0 
RPLOT 0*0 


50,50 



+ 0 , +0 


+ 20,+10 


+ 20,+0 


Note that the command RPLOT 0,0 returns the pen to the local origin (50,50) not the real 
origin (0,0). Since RPLOT creates a local origin it is useful when drawing a figure that needs to 
be repeated at different locations on the display. 

Line Rotation 

Lines generated by move, draw, and plot can be rotated by the PIVOT statement. The current 
angle mode is used to specify the rotation. 

DEG 

GCLEAR 
PI MOT 45 
MOUE 0*0 
DRAW 100*0 

PI MOT 0 will return the system to normal. 
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How Colored Lines Are Drawn 

Color displays compatible with the HP 98627 work on the principle of using combinations of 
three primary colors to represent the available colors. The primary colors are Red, Green, and 
Blue. Secondary colors are Yellow (Red combined with Green), Cyan (Green combined with 
Blue), and Magenta (Red combined with Blue). White is produced by combining the three 
primary colors, and Black is the lack of all three colors. 

The primary colors may be conceptually grouped into three “planes” of dots, which are 
superimposed to create the visual color image. Thus, each pixel on the screen is composed of 
one primary-color dot from each of the three primary-color planes; the different colors are 
produced by turning on different combinations of dots. 

When a line is drawn using one of the primary colors, dots in the primary-color plane are turned 
on by setting the appropriate bit in the corresponding primary-color memory plane. When a 
line is drawn using one of the secondary colors, two dots, one dot from each of two color 
planes, are turned on for each point drawn. For example, when Yellow is drawn, Red and 
Green dots are turned on at each point of the line to produce this secondary color. When White 
is drawn, all three primary colors are turned on at each point plotted. Drawing with the Comple¬ 
ment pen may be more easily understood by studying the following chart and accompanying 
text. 


Pen 

Number 

Resultant 

Action 

Effect on Each Color Plane: 

Red Green Blue 

-7 

Erase Magenta 

0 

— 

0 

-6 

Erase Blue 

— 

— 

0 

-5 

Erase Cyan 

— 

0 

0 

-4 

Erase Green 

— 

0 

— 

-3 

Erase Yellow 

0 

0 

— 

-2 

Erase Red 

0 

— 

— 

-1 

Erase White 

0 

0 

0 

0 

Complement 

Invert Bit in Each Plane 

1 

Draw White 

i 

1 

1 

2 

Draw Red 

i 

0 

0 

3 

Draw Yellow 

i 

1 

0 

4 

Draw Green 

0 

1 

0 

5 

Draw Cyan 

0 

1 

1 

6 

Draw Blue 

0 

0 

1 

7 

Draw Magenta 

1 

0 

1 


The chart shows how bits of each primary-color memory plane are affected by drawing lines 
with each pen color. A “1” in a column indicates that a bit in that color plane is set when the 
color is drawn, a “0” indicates that a bit is cleared, and a “—” indicates that bits in that color 
plane are unaffected by drawing (or erasing) with the pen color. 
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Note 

When using the PLOT statements, keep in mind that the optional 
pen control parameter affects only the up/down movement of the 
current pen; it does not change the pen color. See the language 
reference descriptions of the IPLOT, PLOT, and RPLOT statements 
for further details. 


Storing and Loading Display Memory 

The HP 98627A’s display memory is composed of three “color planes” of 32 768 ( = 32K) 
bytes each, for a total of 96 Kbytes of memory. When this memory is displayed, the color 
planes are visually superimposed; that is, the color of each point on the display is determined by 
the combination of Red, Green, and Blue dots which are on at that point. Each color dot is 
turned on when the corresponding bit in that color plane is 1 and turned off when the bit is 0. 

In order to store the current display, use the GSTORE statement. This storage of the HP 
98627A’s display memory into computer memory requires exactly 49 152 ( = 3 x 16 384) 
INTEGER elements. The following program stores the current display memory in the INTEGER 
array Array!#). 

100 PLOTTER IS 28 ,"386274" ! Define plotter, 

no i 

120 INTEGER Array(1 :3 , 1:18384) ! 49152 elements. 

130 GSTORE Array!*) 

140 DISP "Display Stored." 

150 BEEP 

1 BO WAIT 2 

170 ! 

180 GCLEAR 

18 0 DISP "Display Cleared," 

200 BEEP 

210 WAIT 2 

220 ! 

230 G L 0 A D Array!*) 

240 DISP "Display Re-Loaded." 

250 BEEP 

260 ! 

270 END 


Refer to GLOAD and GSTORE in the BASIC Language Reference manual for more information 
on loading and storing the display. 
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The number of pixels in the vertical direction is dependent on the current display format. If the 
“High Resolution” format is in effect, all array elements are shown. If a smaller display format is 
in use, only the first elements of each memory plane are displayed. Thus, if the Standard 
graphics” format is being used (512 by 390 pixels), only the first 12 480 elements of each 
primary-color plane are displayed. 

The GLOAD statement can be used to load the display. Either a previously stored display or a 
software-generated numeric array can be used. 

Dumping to an External Device 

The DUMP GRAPHICS statement or the (DUMP GRAPHICS) key can be used to dump the screen 
contents to the current DUMP DEVICE IS device. Each pixel sent to the destination device is 
represented by the state of one bit, and the state of each bit is determined by performing an 
inclusive-OR function on corresponding bits of each primary-color memory plane; thus, no 
color information is sent to the dump device by this type of operation. Examples are as follows. 


1 0 0 

110 

PLOTTER IS 28 »"HP98827 A" 
DUMP DEMICE IS Printer 




400 

G50 

810 

DUMP GRAPHICS 

DUMP GRAPHICS #801 

DUMP GRAPHICS CRT TO #702 ! 

! 38827 to 
! 98G27 to 
INTERNAL 

Printer, 
d e u i c e 801. 
GRAPHICS to device 


If EXPANDED is specified in the DUMP DEVICE IS statement, the image is doubled in both X 
and Y directions before being sent to the destination device. However, if both source and 
destination are explicitly specified, no expansion is performed. Examples are as follows. 

100 DUMP DEMICE IS 701^EXPANDED 

200 DUMP GRAPHICS ! Expand and send. 

450 DUMP GRAPHICS 28 TO #701 ! Send without expanding. 
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Interactive Graphics 

The GRAPHX extension provides the computer with the abilities of accepting inputs from a 
graphics device and optionally “echoing” these inputs on the graphics output device. The following 
abilities are provided. 

• The ability to digitize individual points on the input (GRAPHICS INPUT IS) device. Each point 
is selected by first positioning the input device’s locator (typically a cursor or stylus) and 
pressing the “Digitize” button (or the stylus). 

• The ability to track the locator’s position on the output (PLOTTER IS) device while waiting for 
a point to be digitized. The locator’s position is shown by either a “cross-hair” or by the output 
device’s pen position, depending on the type of plotter device. 

• The ability to “continuously” monitor the locator’s coordinates. 

• The ability to move the output device’s cross-hair (or pen), independent of the locator’s 
position. 

• The ability to monitor the Digitize button to determine whether or not it is currently being 
pressed. 
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Compatible Devices 

This software is intended for use with Hewlett-Packard Graphics Language (HPGL) graphics 
devices. The software currently supports several different types of input and output devices. 

Output Devices 

At this time, the software can be used with the following HP graphics-output (PLOTTER IS) 
devices. 

• HP 98627A Color Output Interface driving an external color monitor. 

• The internal graphics device of Series 200 computers. 

• HPGL plotters, in general; examples include the HP 7470 and HP 7580 plotters. 

Input Devices 

At this time, compatible graphics-input (GRAPHICS INPUT IS) devices include the following: 

• HP 9111 Graphics Tablet. 

• HP 9874 Digitizer. 

• HPGL plotters, in general. 

• Keyboards (arrow keys, knob, mouse, etc.) 

Setting Up a Session 

Using the interactive graphics capabilities requires a few simple program steps and programmer 
considerations. Both input and output graphics devices must be defined by the program. Your 
main consideration is how the usable area of the input device maps onto the usable area of the 
output device, which is discussed in the “Graphics Regions and Mapping” section that follows 
the first programming example. 

Specifying the Output Device 

The PLOTTER IS statement is used to specify which device is to be the output device. Several 
example statements are shown below. 

PLOTTER IS 28 ♦"98G27A" 

PLOTTER IS 705 ♦"HPGL" 

PLOTTER IS 3 ♦ "INTERNAL" 

Specifying the Input Device 

The GRAPHICS INPUT IS statement is used to specify which device is to be used for graphics 
input. Example statements are shown below. 


GRAPHICS 

INPUT 

IS 

70S 

♦"HPGL 

GRAPHICS 

INPUT 

IS 

805 

♦"HPGL 

GRAPHICS 

INPUT 

IS 

KBD 

♦"KBD" 


aqj smogs ajrtq sim io anjeA am ‘DaummC* c. a ,Z"” ~' 1 ' L ui uotdst 

—.. -4 S! 


bajndiuoa agt asned m (pTTdTO) Suissay quauiaiejs q7I , Inir7 am K P aj ! sa P P 

papajas sj jutod ou it juWlaTeis mcwa i Va „ 9L P uo « 6 ub M,, U!M lajnduioo agj 

am °I sapumiooo s,L d a!^ Z2 SS 1*!“ U8 * UBa a Hl ^nduioo 
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Interactive Graphics 

The GRAPHX extension provides the computer with the abilities of accepting inputs from a 

graphjcs device and optionally “echoing” these inputs on the graphics output device. The followinq 
abilities are provided. 

• The ability to digitize individual points on the input (GRAPHICS INPUT IS) device. Each point 
is selected by first positioning the input device’s locator (typically a cursor or stylus) and 
pressing the “Digitize” button (or the stylus). 

• The ability to track the locator’s position on the output (PLOTTER IS) device while waiting for 
a point to be digitized. The locator’s position is shown by either a “cross-hair” or by the output 
device’s pen position, depending on the type of plotter device. 

• The ability to “continuously” monitor the locator’s coordinates. 

• The ability to move the output device’s cross-hair (or pen), independent of the locator’s 
position. 

• The ability to monitor the Digitize button to determine whether or not it is currently being 
pressed. 
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Compatible Devices 

This software is intended for use with Hewlett-Packard Graphics Language (HPGL) graphics 
devices. The software currently supports several different types of input and output devices. 


Output Devices 

At this time, the software can be used with the following HP graphics-output (PLOTTER IS) 
devices. 

• HP 98627A Color Output Interface driving an external color monitor. 

• The internal graphics device of Series 200 computers. 

• HPGL plotters, in general; examples include the HP 7470 and HP 7580 plotters. 

Input Devices 

At this time, compatible graphics-input (GRAPHICS INPUT IS) devices include the following: 

• HP 9111 Graphics Tablet. 

• HP 9874 Digitizer. 

• HPGL plotters, in general. 

• Keyboards (arrow keys, knob, mouse, etc.) 

Setting Up a Session 

Using the interactive graphics capabilities requires a few simple program steps and programmer 
considerations. Both input and output graphics devices must be defined by the program. Your 
main consideration is how the usable area of the input device maps onto the usable area of the 
output device, which is discussed in the “Graphics Regions and Mapping section that follows 
the first programming example. 

Specifying the Output Device 

The PLOTTER IS statement is used to specify which device is to be the output device. Several 
example statements are shown below. 

PLOTTER IS 28 ^eeGZTA" 

PLOTTER IS 705 >“HPGL" 

PLOTTER IS 3 t "INTERNAL" 

Specifying the Input Device 

The GRAPHICS INPUT IS statement is used to specify which device is to be used for graphics 
input. Example statements are shown below. 


GRAPHICS 

INPUT 

IS 

70S 

>"H PGL 

GRAPHICS 

INPUT 

IS 

805 

>"HPGL 

GRAPHICS 

INPUT 

IS 

KBD 

>" KBD" 
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Interactive Graphics Techniques 

The programming techniques in this section show the most common uses of the interactive graphics 
capabilities. The examples show digitizing single points, digitizing with tracking, and drawing con¬ 
tinuous lines. 

Digitizing Single Points , , 

“Digitizing a point” simply means that the point’s “X” and “Y” coordinates are determined^ 
The point to be digitized is specified by locating the point with the input device s locator and 
then pressing the Digitize button (or pressing the stylus). The following program shows a simple 
technique for single-point digitizing. The input device is an HP 9111 Graphics Tablet. 


1 0 0 
i 10 
120 
130 
140 
150 

1 GO 
170 
180 
190 

2 0 0 
210 
220 
230 
240 
250 
260 
270 
280 
290 
300 
310 
320 


GINIT ! Initialize* 

GRAPHICS INPUT IS 70S t " HPGL" ! Sill Graphics Tablet. 

j 

Point: DIGITIZE X»Y»Status$ ! Request coords. 

! and status. 

! Print coords. 

DISP USING "#>" "X=" " »K»2X»""Y = " " »K»2X"5X»Y 
! 

! Which re Si on is point in? 

ReSion$=Status$C3511 ! Read 3rd character. 

SELECT R e Sio n $ ! Determine re Si on. 

CASE = " 2 11 

DISP "(Inside VIEWPORT)" 

CASE = " 1 " 

DISP "(Outside VIEWPORT»"5 
DISP " but inside P1»P2)" 

CASE ="0" 

DISP "(Outside PI»P2)" 

END SELECT 

I 

GOTO Point 

i 

END 


Executing the DIGITIZE statement causes the following action. The computer first tells the 
GRAPHICS INPUT IS device that it is to digitize a point. The input device then waits for the 
Digitize button to be pressed (in this case, for the stylus to be pressed), at which time it 
determines the point’s coordinates. The input device then returns the point s coordinates to the 
computer The computer can then execute the next BASIC statement. If no point is selected, 
the computer will “hang” on the DIGITIZE statement. Pressing (CLRJ/0) will pause the computer, 

if desired. 

The optional string variable (S t a t u s $ in the preceding program) is used to return information 
about the input device. Here, only the third byte is examined; the value of this byte shows the 
region in which the point is located. The values 2, 1, and 0 can be returned; the respective 
definitions are shown in the program. 
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Graphics Regions and Mapping 

harH re HinT ly * eT f oned ’ th f m f imum usab,e ar «a of a graphics device is bounded by its 
output dLicT 6XamP ’ Pen Cann0t ^ made t0 dmW ° UtSide these lim *s on an 

The current usable area is bounded by the rectangle defined by the points PI and P2- the 
manual!' ”^^3^ ^ °" ™ 

^ hen ,' he PL N,T ? atemen ! or a PLOTTER IS statement Is executed, points PI and P2 are read 

vatee of RATICnffh'TP S' NIT ’P l '? , ‘" 13 device ls assumed to be the Internal CRT. The 
value of RATIO is then set to the result of the following calculation: 

RATIO = (P2x - Plx)/(P2y - Ply) 

The operating system then automatically scales the P1,P2 rectangle. When GINIT is executed 
the following VIEWPORT and WINDOW statements are executed, scaling the recZdet 
Graphic Display Units and User Defined Units, respectively. S 


If RATIO > si: 

VIEWPORT 0 »100*RATI0,0,100 
WINDOW 0,10 0 * R A TI 0 ,0,100 


If RATIO < 1: 

V IEWP0RT 0,100 ,0,1 00/RATI 0 
WINDOW 0,100,0,10 0/R A TI 0 


As seen above, the X and Y coordinates of PI are always both 0 Graphic Display Units The 
default Graphic Display Unit coordinates of P2 depend on the device; however ^he smaller 
coordinate of this point is always 100 Graphic Display Units. Two examples are shown bdow 


100 GDUs 


-133 GDUs - 


P2 
(100,133) 


MODEL 226 

CRT Graphics Raster 


PI 

( 0 , 0 ) 


Usable-Area Boundaries: 

Left edge = X coordinate of PI 
Bottom edge = Y coordinate of PI 
Right edge = X coordinate of P2 
Top edge = Y coordinate of P2 


100 GDUs 


□□□□ □□□□ □□□□ ponn 


Default P2 
(100,141) 


HP 9111 

Graphics Tablet Platen 


Default Pi 
_ ( 0 , 0 ) 


141 GDUs ■ 


Default Locations of PI and P2on the Model 226 and HP 9111 
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When a PLOTTER IS statement is executed, the locations of points PI and P2 on the specified 
device are determined. The current VIEWPORT statement parameters are then used to define 
the physical area (in GDUs) which is to be scaled (in UDUs) by the WINDOW or SHOW 
statement currently in effect. 

When a subsequent GRAPHICS INPUT IS statement is executed, the operating system attempts to 
apply the current VIEWPORT and WINDOW (or SHOW) parameters to the P1,P2 rectangle of the 
input device. In the preceding example, the two usable areas are not identical in size (in Graphic 
Display Units), since the HP 9111 has a smaller horizontal-to-vertical aspect ratio. The P2 of the 
input device will automatically be adjusted to equal the GDU’s of the output device. 

Digitizing with Tracking 

The locator may also be “tracked” on the output device while it is being moved (before a point 
is digitized). Executing the TRACK...IS ON statement accesses this feature, as shown in the 
following example program. 


1 0 0 

GINIT 

! Restore defaults. 

110 

GRAPHICS INPUT IS KBD,"KBD" 

! Keyboard is input. 

120 

PLOTTER IS CRT»"INTERNAL" 

! ( R e d u n d a n t. ) 

130 

TRACK CRT IS On 

! Enable tracking. 

140 

i 


150 

GRAPHICS ON 


1B0 

WINDOW -50 >50>-20>20 ! 

Define UDUs. 

170 

FRAME ! 

Draw b ound s. 

180 

AXES 10 »10 >0 >0 >5 >5 ! 

Draw axes. 

190 

200 

MODE 0,0 '■ 

I 

Be S i n at Origin. 

210 

220 

j 

Track: DIGITIZE X,Y,Status* ! 

Request coords., 

230 

! updating cursor unti1 

coords, received. 

240 

! 


250 

DRAW X ,Y ! 

Connect points. 

2G0 

j 


270 

GOTO T rack 


280 

! 


290 

END 



The TRACK .IS ON statement merely enables the tracking feature; the actual tracking is 
performed while the DIGITIZE statement is being executed. The locator is “tracked” by moving 
the output device’s “cross-hair” (or pen) correspondingly. Notice that the definition of the 
DIGITIZE statement has been modified slightly — now its execution causes the locator to be 
tracked and “echoed” on the output device until the stylus (or Digitize button) is pressed. 

After a key satisfying the digitize is pressed, the DIGITIZE statement has finished execution and the 
DRAW statement is executed. This program draws lines between the digitized points, but you may 
want to change this response as desired with the appropriate software. 
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Drawing Continuous Lines 

Other common uses of interactive graphics are to draw lines or track the cursor continuously 
without digitizing. The READ LOCATOR and SET ECHO statements are used in order to 
determine the input device’s locator position and to echo the position on the output device, 
independent of the Digitize button being pressed. The following program shows an example of 
implementing this graphics capability in a BASIC program. 

100 GINIT | 

110 GRAPHICS INPUT IS 70S > " HPGL" ! 

120 PLOTTER IS CRT»"INTERNAL" 

130 GRAPHICS ON 

140 WIND0N 0 »100 > 01 100 ! 

150 FRAME i 

ISO ! 

170 LOOP 

180 READ LOCATOR X»Y»Status* 

190 SET ECHO X»Y 

200 Bu11 o n $ = S t a t us $ C 1 > 1 ] 

210 G0SUB Action 

220 END LOOP 

230 ! 

240 Action: IF Button$="0" THEN MODE 

250 IF Bu11on$ ="1" THEN DRAN 

2B0 RETURN 

270 | 

280 END 

The preceding program continuously tracks the input locator and monitors the pressed/not- 
pressed status of the Digitize button (or stylus). The cursor position is continuously echoed on 
the output device, and lines are drawn if the Digitize button (or stylus point) is pressed. 

Interactive Color Graphics 

The interactive graphics statements can also be used with the Color Output Interface. The 
following program shows a typical example of using the interface for this type of graphics 
application. 


Restore defaults, 
Define input. 


Define UDUs, 
Draw limits, 
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100 

PLOTTER 

IS 28 » " 

98G27A" 


! Define output. 

110 

GRAPHICS 

INPUT 

IS 70S f " 

HPGL " 

! Define input. 

120 

! May want to watch aspect ratios with VIEWPORT? 

130 

! parameters depend on 

color-i 

display format. 

140 

! May also want 

to moue 

PI > P2 

with HPGL commands 

150 

! 






1 GO 

! Define 

s f K ' s , 




170 

ON KEY 

0 

LABEL 

"White " 

GOSUB 

White 

180 

ON KEY 

1 

LABEL 

"Red 

GOSUB 

Red 

190 

ON KEY 


LABEL 

"Yellow" 

GOSUB 

Y e 11 o w 

200 

ON KEY 

3 

LABEL 

"Green " 

GOSUB 

Green 

210 

ON KEY 

5 

LABEL 

"Erase " 

GOSUB 

Erase 

220 

ON KEY 

9 

LABEL 

"Clear " 

GOSUB 

Clear 


230 ! 

240 LOOP 

250 READ LOCATOR X»Y»Status$ 

2G0 SET ECHO X»Y 

270 Action$=Status$[1>13 

280 GOSUB Action 

230 ! 

300 END LOOP 
310 ! 

320 White: PEN 1 
330 RETURN 

340 ! 

350 Red: PEN 2 

3GO RETURN 

370 ! 

380 Yellow: PEN 3 
390 RETURN 

400 ! 

410 Green: PEN 4 
420 RETURN 

430 ! 

440 Erase: PEN - 1 
450 RETURN 

4 GO ! 

470 Clear: GCLEAR 
480 RETURN 

490 ! 

500 Action: IF Action$="0" THEN HOME X>Y 
510 IF Action**"1" THEN DRAW X»Y 

520 RETURN 

530 ! 

540 END 


The program uses special function keys to change the color of the lines drawn by pressing the 
stylus onto the platen. The program can be expanded easily to draw and erase all colors, if 

desired. 
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Example Graphics Programs 

The following programs use graphics to help illustrate the operation of several of the graphics 
statements available in BASIC. You may wish to modify or entirely rewrite the programs to 
better understand how the statements work. 










Sin 

10 

20 

30 

40 

50 

GO 

70 

80 

90 

100 

110 

120 

130 

140 

150 

1 GO 

170 

180 

190 

200 

210 

220 

230 

240 

250 

2G0 

270 

280 

290 

300 

310 
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Program: 9INE 


Shows some basics of drawing arid labeling* 


DEG 

GINIT 

GRAPHICS ON 
PRINT CHR$(12)5 
WINDOW -100tBOO i-2 *2 
AXES 9 0 » ♦ 5 
! 

LORG G 

FOR 1=0 TO 720 STEP 90 
MOOE I»0 
LABEL I 
NEXT I 

i 

LORG 8 

FOR I=-l*5 TO 1♦5 STEP *5 
MOOE 0»I 
LABEL I 
NEXT I 

i 

LORG 5 

MOOE 450 »1*75 

LABEL "Plot of SIN(X)" 

| 

MOOE 0 >0 

FOR X = 0 TO 720 

DRAW XtSIN(X) 

NEXT X 
! 

END 


! DEGREES 
! INITIALIZE 
! RASTER ON 
! CLEAR ALPHA 
! SET WINDOW 
! DRAW AXES 

! LABEL X AXIS 


! LABEL Y AXIS 


! LABEL PLOT 


! PLOT SINE 
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Axes 



Major Tick 

Minor Tick 


i—i—|—i—h 


10 
20 
30 
40 
50 
GO 
70 
80 
90 
100 
110 
120 
130 
140 
150 
1 GO 
170 
180 
190 
200 
210 
220 
230 
240 
250 
260 
270 
280 
290 
300 
310 
320 
330 
340 
350 
360 
370 
380 
390 


Program: AXES 


Draw and label the AXES statement* 


GINIT 

GRAPHICS ON 
ALPHA OFF 
! 

X1o c = 20 
Y1 o c = 2 0 
X m a J = 4 
Y m a J = 2 
S i 2 e = 8 


X AXIS LOCATION 
Y AXIS LOCATION 
MAJOR TICK COUNT 
MAJOR TICK COUNT 
LENGTH OF TICKS 


FOR 1=100 TO 10 STEP -1 
PEN -1 

AXES X tic ,Y tic, X1o c,Y1o c,Xma J,Ym a J,Siz e 
X t i c = I 
Y t i c = I 


PEN 1 

AXES X tic ,Y tic,X1o c,Y1o c,Xm a J,Ym a J,Size 
NEXT I 


i 


MOUE X1o c , Y1 o c ! LABEL THE AXES 

I DRAW 20 #20 
LABEL "X1o c > Y1 o c" 

M 0 0 E X1 o c + 4 0 , Y1 o c 
IDRAW 20,30 
LABEL "Major Tick" 

M 0 0 E X1 o c + 5 0 , Y 1 o c 
IDRAW 10,15 
LABEL "Minor Tick" 

MOUE XI oc-Size/2,Y1oc + 40 
DRAW 40,80 

MOUE Xloc + Size/2 ,Y1oc + 40 

DRAW 40,80 

LABEL "Tick Size" 

! 

END 
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Grid 
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10 ! Program: GRID 

20 ! 

30 ! S h o iaI s various size sf r i d s ♦ 

40 ! 

50 GINIT 

GO GRAPHICS ON 

70 PRINT CHR$ (12) 5 

80 ! 

90 WINDOW -110»100#-110#110 

100 ! 

110 Y1oc = 0 ! CENTER AT 0 *0 

120 X1o c = 0 

130 XmaJ=G 

140 YmaJ = 2 

150 Siz e = 20 

ISO ! 

170 LORG 4 

180 ! 

190 FOR 1=10 TO 100 STEP 2 

200 Xtic = I 

210 Y tic = I 

220 GCLEAR 

230 MOOE 1/2 »0 

240 LABEL I 

250 GRID Xtic»Ytic»X1oc»Y1oc»XmaJ»YmaJ»Size 

2G0 WAIT (100-D/100 

270 NEXT I 

280 ! 

290 WAIT 2 

300 GRAPHICS OFF 

310 END 
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10 

! Pros rain: CSIZE 


20 

i 


30 

! VARIABLE SIZE CHARACTERS 

40 

! 


50 

ON KEY 0 LABEL " HEIGHT 

" GOSUB F 1 a 3 

GO 

ON KEY 1 LABEL " RATIO" 

GOSUB Fla<S_ 

70 

ON KEY a LABEL " QUIT" 

GOTO Quit 

80 

PRINT CHR$(12) i 


90 

DISP "ROTATE KNOB TO CHANGE SIZE."! 

100 

ON KNOB ,2 GOTO Change 


110 

! 


120 

H = 5 

! HEIGHT 

130 

W= *G 

! HEIGHT/UII 

140 

GOTO Gize 


150 

! 


ISO 

Charge: ! CHANGE THE CHARACTER SIZE 

170 

IF F1 a $ THEN 


180 

W = H + K N 0 B X / 10 0 


190 

IF W<*01 AND W>0 THEN 

W = 0 

200 

ELGE 


210 

H = H + K N 0 B X / 1 0 


220 

END IF 


230 

DIGP 


240 

DISP USING "2X13A »3D♦D" 

5" h ="; h ;" r = 

250 

! 


2 GO 

Size: GINIT 


270 

GRAPHICS ON 


2B0 

CSIZE Ht W 


290 

NODE G7 >50 


300 

LORG 5 


310 

LABEL "SIN(X)" 


320 

GOTO 320 

! WAIT HERE 

330 

j 


340 

F 1 a s _ o n : F1 a =1 


350 

RETURN 


360 

! 


370 

F1 a$_of f : F1 a5 = 0 


380 

RETURN 


390 

j 


400 

Quit: GRAPHICS OFF 


410 

OUTPUT 2 USING 11 # ,B' 

' 5255 175 

420 

END 
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Label 




10 ! Program: LABEL 

20 ! 

30 DEG 

40 GINIT 

50 GRAPHICS DN 

GO C1 e a r_c rt $=CHR$ ( 255 ) &=CHR$ ( 75 ) 

70 OUTPUT 25Clear_crt$5 

80 SHOW -100 * 100 t- 100»100 

SO ! 

100 FOR 1=0 TO 3G0 STEP 22*5 ! NON-ROTATED 

110 NODE -GO >0 

120 PI MOT I 

130 I DRAW 40 *0 

140 LORG 5 

150 LABEL "hp" 

160 NEXT I 

170 ! 

180 FOR 1=0 TO 360 STEP 22*5 ! ROTATED 

ISO MODE GO >0 

200 PI DOT I 

210 IDRAW 40 tO 

220 LORG 2 

230 LDIR I ! NOTE LDIR USED 

240 LABEL "hp" 

250 NEXT I 

2G0 ! 

270 END 

















366 Graphics 


Ginit 


ZD \ r\c\6 iD 9219V9?1 


10 

20 

30 

40 

50 

GO 

70 

80 

90 

100 

110 

120 

130 

140 

150 

ISO 

170 

180 

190 

200 

210 

220 

230 

240 

250 


Program: GINIT 


! This pros raw does a specialized 'GINIT 7 
! 

PRINT CHR$(12)5 ! CLEAR SCREEN 

j 

! CUSTOMIZED 'GINIT 7 

j 

PLOTTER IS 3 #"INTERNAL" 

CLIP OFF 
PI MOT 0 
PEN 1 

LINE TYPE 1#5 
LORG 5 
CSIZE 8#-,G 
LDIR 0 
MOVE 90 #60 
GCLEAR 

VIEWPORT 0 #RAT 10*100 #0>100 
WINDOW 0#RATI0*100#0#100 

j 

GRAPHICS ON 

LABEL "Reverse Graphics" 

LIST GO#230 
END 
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10 
20 
30 
40 
50 
GO 
70 
80 
90 
100 
110 
120 
130 
140 
150 
1 GO 
170 
180 
190 
200 
210 
220 
230 
240 
250 
260 
270 
280 
290 
300 
310 
320 
330 
340 
350 
3G0 


! Programs ROSE 

! 

! Rotate the Knob* change the uiew. 

! 

DEG 

GINIT 

GRAPHICS ON 
PRINT CHR*(12)5 
ON KNOB ♦1 GOTO Scale 
! 

Max=40 ! starting value 

! 

Scales Max=Max+KNOBX 
IF Max<1 THEN Max = l 
DISP Max 

i 

IF Max >72 THEN 
Dx=Max-72 

SHOW -51+Dx »5 0 - D x»- G 3 + D x * G 2 - D x 
ELSE 

OIEWPORT G2-Max*62+Max *50-Max*50+Max 
WINDOW -50#50»-62*62 
END IF 
GCLEAR 
FRAME 

AXES 10*10#0 *0 
FOR 1=0 TO 180 STEP 2 
P=40*C0S(7*I) 

X = P * C 0 S (I) 

Y = P*SIN( I ) 

IF 1=0 THEN MODE X*Y 
DRAW X #Y 
NEXT I 

GOTO 170 
END 



















368 Graphics 


Rplot 




-A/V^ 

-AAA- 

-w- 


-A/V^- 

-a/v^ 

“W- 


-A/V^ 

-w- 
a/v^ 


-w- 

-A/V^ 

-aa^ 

“W^- 

-w- 

-W- 


-a/vH 
-w- 

-W- 
-AV^- 


-A/V^- 

-w- 


-w- 

-A/V^ 




10 ! Program: RPLOT 

20 ! 

30 ! Repeats an i m a s e at carious locations* 

40 ! 

50 DEG 

GO GINIT 

70 GRAPHICS ON 

80 WINDOW -10 (370 t- 100 1100 

90 PRINT CHR$(12) ! ! CLEAR SCREEN 

100 DISP " RPLOT" 

110 FRAME 

120 ! 

130 FOR 1=0 TO 3G0 STEP 12 
140 MODE I»S IN ( I)*80 

150 GOSUB Shape 

160 NEXT I 

170 ! 

180 GOTO Quit 

190 ! 

200 Shape: ! DRAW A RESISTER 

210 ! 

220 RPLOT -10.0.1 

230 RPLOT -S.0 

240 RPLOT -4.2 

250 RPLOT -2.-2 

260 RPLOT 0,2 

270 RPLOT 2,-2 

280 RPLOT 4,2 

290 RPLOT 6,0 

300 RPLOT 10,0 

310 RETURN 

320 ! 

330 Quit: END 
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Randomview 




10 ! Program: R A N D 0 M VIE W 

20 ! 

30 RANDOMIZE 

40 ! 

50 Start: ! Demonstration of VIEWPORT and WINDOW 


BO 

! 


70 

DEG 


80 

GINIT 


90 

GRAPHICS ON 


100 

ALPHA OFF 


110 

i 


120 

! Generate some random numhers 

130 

i 


140 

Kmin = RND*131 


150 

Xmax = Xmin + RND#(131-Xmin) 


160 

Y m i n = R N D * 10 0 


170 

Ymax=Ymin+RND*(100-Ymin) 


180 

I 


100 

! Set OIEWPORT to random 

area 

200 

j 


210 

OIEWPORT Xmin t Xmax * Ymin» 

Y m a x 

220 

WINDOW -50>50>-50#50 


230 

FRAME 


240 

I 


250 

! Draw a rose within the 

area 

280 

! 


270 

FOR 1=0 TO 200 


280 

P=40*C0S(11*1) 

! ELEOEN LEAF ROSE 

280 

X=P*COS(I) 


300 

Y = P * SIN ( I ) 


310 

DISP INT(Xmax-Xmin) 5": 

" 51N T ( Y m a x - Y m i n ) 

320 

IF 1=0 THEN MOOE X#Y 


330 

DRAW X »Y 


340 

NEXT I 


350 

380 

1 

GOTO Start 

! DO IT AGAIN 

370 

END 
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Color 


WHITE 

3ED 

YELLOW 

GREEN 

CYRN 

BLUE 

MRGENTR 


WHITE 

RED 

YELLOW 

GREEN 

CYRN 

BLUE 

MRGENTR 


WHITE 

RED 

YELLOW 

GREEN 

CYRN 

BLUE 

MRGENTR 


10 

! Program: COL 

20 

j 

30 

! This program 

40 

! Color Output 

50 

! 

BO 

! Note that a 

70 

! immediately 

80 

i 

90 

! Note differei 

100 

I 

110 

GINIT 

120 

PLOTTER IS 28 t 1 

130 

GRAPHICS ON 

140 

PEN 1 

150 

FRAME 

160 

! 

170 

FOR X = 0 TO 120 

180 

MOVE X #70 

190 

PEN 1 

200 

LABEL "HHITE" 

210 

PEN 2 

220 

LABEL "RED" 

230 

PEN 3 

240 

LABEL "YELLOM" 

250 

PEN 4 

280 

LABEL "GREEN" 

270 

PEN 5 

280 

LABEL "CYAN" 

290 

PEN 8 

300 

LABEL "BLUE" 

310 

PEN 7 

320 

LABEL "MAGENTA" 

330 

NEXT X 

340 

END 


WHITI 

RED 

YELLi 

GREEI 

CYRN 

BLUE 

MRGEI 
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Meter 



10 

20 

30 

40 

50 

GO 

70 

80 

90 


Programs METER 

Simulation of a analog meter 
KNOB arid RANDOM needle movement* 

DEG 

GINIT 

GRAPHICS ON 
CLIP 0 * 131 *25*100 


100 

WINDOW -150*1 

110 

OUTPUT 2 US I K 

120 

! 

130 

FRAME 

140 

FOR Tic = -50 1 

150 

MODE 0*0 

ISO 

PI DOT Tic 

170 

LORG 4 

180 

MODE 0*100 

190 

IDRAW 0 *10 

200 

LABEL -Tic 

210 

NEXT Tic 

220 

j 

230 

ON KNOB ♦ 2 G( 

240 

! 

250 

Meter: ! GENERi 

2G0 

PEN -1 

270 

MOUE 0*0 

280 

DRAW 100*0 

290 

p=(p+4*RND-2 

300 

MODE 0*0 

310 

PIUOT 90-P 

320 

DISP I NT(P) 

330 

PEN 1 

340 

MODE 0*0 

350 

DRAW 100*0 

3G0 

WAIT ♦07 

370 

GOTO Meter 

380 

! 

390 

END 


! CLEAR SCREEN 
! CREATE METER 


10 


! UNDRAW NEEDLE 


! REDRAW NEEDLE 
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Pivot 


MODEL 



10 

! Program: PIVOT 


20 

! 


30 

! Shows pivotins around a point* 

1 


40 


50 

DEG 


BO 

GINIT 


70 

GRAPHICS DN 


80 

PRINT CHR$(12) 5 


90 

DIM X(4) , Y ( 4 ) 


100 

DATA 40,20,0,14,-6,6,-14,0,-20,-40 ■ 

SHAPE 

110 

FOR 1=0 TO 4 

120 

READ X(I) ,Y(I) 


130 

NEXT I 


140 

j 


150 

DATA 80,130,35,85,0,40,50,90 ! 'WINDOWS' 

ISO 

READ SI ,Sr ,Sb ,St ,M1 ,Mr ,Mb ,Mt 

j 


170 


180 

DIM 0 r S x ( 3 ) , 0 r a y(3) 


190 

DATA 40,60,40,40,20,20,0,0 ! ORIGINS 


200 

FOR 1=0 TO 3 


210 

READ Orsx(I) ,0 rsfy ( I ) 


220 

NEXT I 


230 

MOVE 10,95 


240 

LABEL "MODEL" 


250 

MOVE 90,90 


2G0 

LABEL "WITH PIVOT" 


270 

LINE TYPE 8 


280 

MOVE Ml ,Mb ! CONNECT 

LINES 

290 

DRAW SI ,Sb 

300 

MOVE Mr,Mb 


310 

DRAW Sr ,Sb 


320 

MOVE Mr ,Mt 


330 

DRAW Sr,St 


340 

MOVE SI ,St 


350 

DRAW Ml ,Mt 


3B0 

j 


370 

MOVE Ml ,Mt 


380 

P=1 


390 

LINE TYPE 1 


400 

0 x = 0 r s x (Index) 


410 

0 y = 0 r s y ( I n d e x ) 


420 

GOSUB Model 


430 

! 
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440 

VIEWPORT SI »Sr»Sb »St 


450 

SHOW -25»100#-25»100 


460 

GOSUB Shape 


470 

DIS P " A n a1 e = " 5 A n 31 e 


480 

A n 3 1 e = A n $ 1 e + 5 


490 

IF An 31e< 36 1 THEN 460 


500 

CALL Cursor(Ox >0'/ * - 1 ) 


510 

P = -l 


520 

GOSUB Model 


530 

An 4 1e = 0 


540 

I n d e x = I n d e x + 1 


550 

IF Index>3 THEN Quit 


560 

GOTO 380 


570 

! 


580 

Model: VIEWPORT Ml»Mr»Mb 

t M t 

590 

SHOW -25.100.-25. 

100 

600 

FRAME 


610 

GOSUB Shape 


620 

RETURN 


630 

Shape: ! DRAW IN CURRENT 

'W 

640 

PEN -1 


650 

MOVE 20#20 


660 

FOR 1=0 TO 4 


670 

I DRAW X(I) »Y<I) 


680 

NEXT I 


690 

MOVE OxtOy 


700 

PEN 1 


710 

CALL Cursor(Ox#0y 

#P) 

720 

PIVOT An $ 1e 


730 

PEN 1 


740 

FRAME 


750 

MOVE 20>20 


760 

FOR 1=0 TO 4 


770 

I DRAW X(I) #Y(I) 


780 

NEXT I 


790 

RETURN 


800 

Quit:DISP 


810 

END 


820 

! 


830 

i - SUB PROGRAM - 

840 

! 


850 

SUB Cursor(X»Y#P> 


860 

PEN P 


870 

PIVOT 0 


880 

MOVE X >Y 


890 

IMOVE 5 tO 


900 

IDRAW -10»0 


910 

IMOVE 5>5 


920 

IDRAW 0»-10 


930 

MOVE X »Y 


940 

SUBEXIT 


950 

SUBEND 



PIVOT POINT 
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Showwindow 


MODEL 



10 ! PROGRAM: SHOWWINDOW 

20 ! 

30 ! Compares the mappin S of SHOW arid WINDOW 

40 ! 

50 DEG 

60 GINIT 

70 GRAPHICS ON 

80 DISP "WINDOW AND SHOW" 

90 DIM X(200)»Y(200)»Center$C40] 

100 FOR 1=0 TO 180 

110 R= 100*C0S(5*1) 

120 X(I)=R*COS(I) 

130 Y ( I)= R*S IN(I) 

140 NEXT I 

150 ! 

160 ! Determine if runnins on a 982S or S83G. 

170 ! Needed for centering of prompti 

180 IF RATI0M.32 THEN 

190 Space=20 

200 ELSE 

210 Space=35 

220 END IF 

230 FOR 1=1 TO Space 

240 Center$=Center$&" " 

250 NEXT I 

260 ! 

270 ! 

280 DATA 0.30.0.50.57.77.75.95 

280 READ Sl.Sr.Sb.St.Ml.Mr.Mb.Mt 

300 ! 

310 Loop: ! FRAME THE PLOTTING AREAS 

320 GINIT 

330 PRINT CHR$(12) i 

340 ALPHA OFF 

350 W r=131 

360 Wl=Wr-Sr 

370 Wt=St 

380 Wb=Sb 

390 VIEWPORT SI ,Sr .Sb .St 

400 FRAME 

410 VIEWPORT Ml.Mr.Mb.Mt 

420 FRAME 

430 VIEWPORT Wl.Wr.Wb.Wt 
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440 

FRAME 

450 

0IEWPORT 0>131♦36 *0 >100 

4S0 

i 

470 

LINE TYPE 5 

480 

MOOE Ml t Mb 

490 

DRAW SI*Sb 

500 

MOVE Mr >Mb 

510 

DRAW Sr »Sb 

520 

MOOE Mr »Mt 

530 

DRAW Sr>St 

540 

MOOE SI*St 

550 

DRAW Ml»Mt 

5 GO 

LINE TYPE 6 

570 

MOOE Ml #Mb 

580 

DRAW W1tWb 

590 

MOOE Mr »Mb 

GOO 

DRAW Wr»Wb 

G1 0 

MOOE Mr »Mt 

620 

DRAW Wr »Wt 

830 

MOOE Ml»Mt 

G40 

DRAW W1 >Wt 

850 

j 

GGO 

LINE TYPE 1 

870 

OIEWPORT 0*131.36*0*100 ! 

G80 

WINDOW 0*131♦36 tO *100 

690 

LORG 1 

700 

MOOE Ml t Mt 

710 

LABEL "MODEL" 

720 

MOOE SI>St 

730 

LORG 1 

740 

LABEL "SHOW" 

750 

MOOE Wr > W t 

760 

LORG 7 

770 

LABEL "WINDOW" 

780 

j 

790 

FOR 1=1 TO 180 

800 

LINE TYPE 1 

810 

OIEWPORT Ml>Mr t Mb»Mt 

820 

SHOW -100*100*-100*100 

830 

MOOE X(I - 1) »Y(I - 1) 

840 

DRAW X<I) *Y(I) 

850 

OIEWPORT SI »Sr»Sb >St 

880 

SHOW -100 * 100*-100»100 

870 

MOOE X(I - 1 ) * Y(I — 1 ) 

880 

DRAW X(I) *Y(I) 

890 

OIEWPORT W1 »Wr»Nb »Wt 

900 

WINDOW -100»100»-100 * 100 

910 

MOOE X(I - 1 ) * Y( I - 1 ) 

920 

DRAW X(I) *Y< I ) 

930 

NEXT I 

940 

! 

950 

DISP Center$5"NEW RATIO" 

960 

OUTPUT 2 5Cen t e r$ 5 

970 

INPUT ""»Ra 

980 

IF Ra< = 0 THEN Quit 

990 

IF R a > =1 THEN 

1000 

S r = 49 

1010 

St = GO/Ra 

1020 

ELSE 

1030 

St = 60 

1040 

S r = 49*Ra 

1050 

END IF 

1060 

GOTO Loop 

1070 

j 

1080 

QuitsGRAPHICS OFF 

1090 

OUTPUT 2 USING "* *B" 

1100 

END 


'SHOW' lines 


'WINDOW' LINES 


LABELS 


DRAW A 
PLACES 


ROSE IN 
AT ONCE 


THREE 
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Gload 



12 3 4 


10 
20 
30 
40 
50 
GO 
70 
80 
90 
100 
110 
120 
130 
140 
150 
1 GO 
170 
180 
190 
200 
210 
220 
230 
240 
250 
260 
270 
280 
290 
300 
310 
320 
330 
340 
350 
3 GO 
370 
380 
390 
400 
410 
420 
430 
440 


Pro*ram: GLOAD 


! DIMENSION 'PICTURE' ARRAYS 

j 

OPTION BASE 1 

A=7500 ! ARRAY SIZE FOR 982G 

IF RATIO<1*32 THEN A=12480 ! ARRAY SIZE FOR 9836 
ALLOCATE INTEGER P1(A) * P2(A) * P3(A) * P4(A) 


DEG 

GINIT 

GRAPHICS ON 
PRINT CHR$(12)5 
DISP "GLOAD/GSTORE" 

SHOW -800»800*-800*800 
! 

GCLEAR 

FOR 1=0 TO 90 STEP .5 ! HEAD 

MODE 0,0 
PI DOT I 
MODE -200*0 
DRAW 200*0 
MODE 0*0 
PIVOT -I 
MOVE -200*0 
DRAW 200*0 
NEXT I 

j 

PEN -1 

FOR 1=0 TO 3G0 STEP 8 ! EYE 

MOVE 40*100 
PIVOT I 
IDRAW 10*0 
NEXT I 

! 

PEN 1 

MOVE 300*0 
LABEL "1" 

GSTORE Pl<*) ! SAVE PICTURE IN ARRAY ' 

BEEP 3400 *♦02 

PEN -1 

MOVE 300*0 

LABEL "1" 



PI ' 
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450 

A = 0 

460 

5=10 

470 

G05UB Mouth 

480 

MOUE 400 *0 

490 

LABEL "2" 

500 

GSTORE P2(*) ! 

510 

BEEP 3400 *♦02 

520 

PEN -1 

530 

MOUE 400 *0 

540 

LABEL "2" 

550 

i 

560 

A = 1 0 

570 

B = 2 0 

580 

GDSUB Mouth 

590 

MOUE 500 *0 

BOO 

LABEL "3" 

610 

GSTORE P3(*) ! 

620 

BEEP 340002 

630 

PEN -1 

640 

MOUE 500 »0 

650 

LABEL "3" 

660 

| 

670 

A = 20 

680 

B = 4 0 

690 

GOSUB Mouth 

700 

MOUE GOO »0 

710 

LABEL "4" 

720 

GSTORE P4(*) ! 

730 

BEEP 340002 

740 

PEN -1 

750 

MOUE GOO »0 

760 

LABEL "4" 

770 

! 

780 

M o u i e : ! a n i m a t i. 

790 

GLOAD Pl(- 

800 

GLOAD P2(■ 

810 

GLOAD P3 (■ 

820 

GLOAD P4 (■ 

830 

GOTO M o vi 

840 

! 

850 

Mouth: PEN -1 

860 

FOR I= A 

870 

MOUE 0*0 

880 

PIUOT I 

890 

DRAW 200 

900 

MOUE 0*0 

910 

PIUOT -I 

920 

DRAW 200 

930 

NEXT I 

940 

PEN 1 

950 

PIUOT 0 

960 

RETURN 

970 

END 


S A U E PICTURE IN ARRAY 


SAME PICTURE IN ARRA'. 


SAME PICTURE IN ARRA'. 


loop 


* 2 


/ P2 / 


'P3' 


# P4 # 
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Transporting Programs 


Chapter 

15 


If you have programs which were written on previous Series 200 BASIC systems, you can use these 
same programs with little or no changes. This chapter describes the differences between BASIC 
2.0/2.1 extensions and BASIC 3.0. 

In general, you can LOAD and RUN BASIC 2.0 programs on BASIC 3.0. The major task you have 
to perform is configure the BASIC 3.0 system with the necessary BIN files. If a program uses 
CSUBs or the PHYREC binary, some additional work is required. 


Configuring BASIC 

BASIC 3.0 is contained in one SYSTM file, several language extension BIN files and several driver 
BIN files. When you configure your system, you choose which files you want to load. There are 
three ways you can do this. 

1. After booting the BASIC 3.0 SYSTM file, load a program and try to run it. Error 1 indicates 
which language extension BIN files are missing. If you LOAD BIN the ERR extension, the 
name of the missing file is given. If the ERR extension is not loaded, the number of the 
missing file is given. These numbers are listed in the Useful Tables Section of the BASIC 
Language Reference. When the error occurs, LOAD BIN the needed BIN file and re-run the 
program. 

If the program uses any interfaces, you must also load the appropriate drivers. An I/O error 
indicates when an interface driver is needed. A mass storage error indicates when a mass 
storage device is needed. 

2. Use the Language History table at the beginning of the BASIC Language Reference Manual. 
Look up the statements your program uses and see which BINs you need to load. For 
example, if your program uses the MAT statement which was located in AP2.0, you now 
need to load the MAT BIN. 

Review the table of device types in the MASS STORAGE IS section of the BASIC Language 
Reference Manual, or the interface table in the Configuration chapter of the BASIC User’s 
Guide. Determine which drivers you need and load them. 

3. The program CONFIGURE on the language extension and drivers discs can help you select 
the BIN files you need and configures the system for you. 

Once you have loaded all the BIN files you need and your program runs, you can store the system. 
Use the STORE SYSTEM statement. This statement is described in both the BASIC User’s Guide 
and in this manual in Chapter 2. A STORE’d system requires a higher capacity mass storage device 
than the Model 226 or 236 internal drive. 
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Statement Changes 


There are several statements added with BASIC 3.0. These are listed below. 


KNOBY 

LIST BIN 

MAXREAL 

MINREAL 

MODULO 

PDIR 

PLOTTER IS file 
PRINT LABEL 


PRINTER IS file 
READ LABEL 
RES 

SCRATCH BIN 
SECURE 
SET LOCATOR 
STORE SYSTEM 
SYSBOOT 


One statement was deleted, RE-STORE BIN. 

KNOBY 

While most of these statements are enhancements which you can chose to use or not, the statement 
KNOBY does effect how a program interprets the rotation of the knob. 

KNOBX returns the number of horizontal knob pulses. KNOBY returns the number of vertical knob 
pulses. In previous BASIC versions, KNOBX returned the total number of pulses without regard for 
vertical or horizontal movement. 

An example program of using KNOBX and KNOBY is included in the “Program Structure and 
Flow” chapter of this manual, in the section Using the Knob. If you have the BASIC 2.0 manual, 
you can compare the programs. 


CSUBs 

If you used Pascal compiled subprograms (CSUBs) in your BASIC 2.0 programs, you will have to 
purchase a Pascal 3.0 system upgrade and a CSUB Utility upgrade to use those CSUBs with 
BASIC 3.0. You recompile the Pascal routine on Pascal 3.0 and re-execute the CSUB utility to 
make the routine look like a BASIC subprogram. 
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PHYREC 

The PHYREC routine which allowed you to read from and write to physical records on a disc is 
changed from a binary program to a CSUB with BASIC 3.0. The PHYREC CSUB is located on the 
BASIC Utilities Disc 1. 

You must append the PHYREC CSUB to your program and change PHYREAD/PHYWRITE 
statements. If the PHYREC binary is appended to a program, a warning message is displayed and 
the binary is ignore by BASIC 3.0. 

Use the followig steps to locate all the lines for an application which uses PHYREC, change them to 
call the PHYREC CSUB and to append the PHYREC CSUB. 

1. Boot a BASIC 2.0 system. 

2. Delete the PHYREC binary. 

LOAD "pro S ram" 

SAME " p r o 3 r a in 2 " - This saves the program without the binary. 

SCRATCH A - This deletes the program and binary from memory. 

GET "pros ram2" - Calls to PHYREC are commented. Write down the line num¬ 
bers. 

RE-STORE "program" 

PURGE "pros raw2" 

3. Attach the PHYREC CSUB. 

LOADSUB ALL FROM "PHYREC" 

This file is located on Disc 1 of the BASIC 3.0 Utilities Library. Do not try to run your 
application until you have completed all steps. 

4. Uncomment and change all the calls to PHYREC. These are the lines you noted in step 2 
above. 

PHY READ Sector >Int_array(*) > Phyread(Sector»Int_array(*)) 
PHYWRITE Sector ilnt_array(*) > Phywrite(Sector 1 1nt_array<*)) 

5. If S e c t o r is declared to be an INTEGER, you need to put it into parentheses so that 
PHYREC will interpret it as a REAL. 

Phy read((Sector) > I n t _ a r r a y ( * )) 

6. The syntax for a conditional call must be changed from: 

IF condition THEN PHYREAD 
to: 

IF condition THEN 

Phy read(Sector ilnt.array(*)) 

END IF 

or to: 

IF condition THEN CALL Phyread(Secto r tint-array(*)) 

7. RE-STORE "prosram" after you have completed the changes. 

8. Boot BASIC 3.0 and run your application. 
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Hardware 

BASIC 3.0 supports hardware which was not available with BASIC 2.0. The new hardware 
includes the HP 46020A keyboard and the HP 9837 with bit-mapped display. 

If you are changing hardware, or your application runs on more than one Series 200 computer, you 
need to check any statement which interfaces with the keyboard or display. Check for information 
on the effects of different hardware on a particular statement in the BASIC Language Reference 
Manual under that statement. 
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Error Messages 


Missing option or configuration error. If a statement requires an option which is not loaded, the 
option number or option name is given along with error 1. These numbers are listed in the Useful 
Tables section. Error 1 without an option number indicates other configuration errors. 

Memory overflow. If you get this error while loading a file, the program is too large for the 
computer’s memory. If the program loads, but you get this error when you press RUN, then the 
overflow was caused by the variable declarations. Either way, you need to modify the program or 
add more read/write memory. 

Line not found in current context. Could be a GOTO or GOSUB that references a non-existent 
(or deleted) line, or an EDIT command that refers to a non-existent line label. 

Improper RETURN. Executing a RETURN statement without previously executing an appropriate 
GOSUB or function call. Also, a RETURN statement in a user-defined function with no value 
specified. 

Improper context terminator. You forgot to put an END statement in the program. Also applies to 
SUBEND and FNEND. 

Improper FOR...NEXT matching. Executing a NEXT statement without previously executing the 
matching FOR statement. Indicates improper nesting or overlapping of the loops. 

Undefined function or subprogram. Attempt to call a SUB or user-defined function that is not in 
memory. Look out for program lines that assumed an optional CALL. 

Improper parameter matching. A type mismatch between a pass parameter and a formal para¬ 
meter of a subprogram. 

Improper number of parameters. Passing either too few or too many parameters to a subprogram. 
Applies only to non-optional parameters. 

String type required. Attempting to return a numeric from a user-defined string function. 

Numeric type required. Attempting to return a string from a user-defined numeric function. 

Attempt to redeclare variable. Including the same variable name twice in declarative statements 
such as DIM or INTEGER. 

Array dimensions not specified. Using the (*) symbol after a variable name when that variable 
has never been declared as an array. 

OPTION BASE not allowed here. The OPTION BASE statement must appear before any dec¬ 
larative statements such as DIM or INTEGER. Only one OPTION BASE statement is allowed in 
one context. 

Invalid bounds. Attempt to declare an array with more than 32 767 elements or with upper bound 
less than lower bound. 

Improper or inconsistent dimensions. Using the wrong number of subscripts when referencing an 
array element. 

Subscript out of range. A subscript in an array reference is outside the current bounds of the array. 

String overflow or substring error. String overflow is an attempt to put too many characters into a 
string (exceeding dimensioned length). This can happen in an assignment, an ENTER an INPUT, 
or a READ. A substring error is an attempted violation of the rules for substrings. Watch out for 
null strings where you weren’t expecting them. 
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19 Improper value or out of range. A value is too large or too small. Applies to items found in a 
variety of statements. Often occurs when the number builder overflows (or underflows) during an 
I/O operation. 

20 INTEGER overflow. An assignment or result exceeds the range allowed for INTEGER variables. 
Must be -32 768 thru 32 767. 

22 REAL overflow. An assignment or result exceeds the range allowed for REAL variables. 

24 Trig argument too large for accurate evaluation. Out-of-range argument for a function such as 
TAN or LDIR. 

25 Magnitude of ASN or ACS argument is greater than 1. Arguments to these functions must be in 
the range -1 thru +1. 

26 Zero to non-positive power. Exponentiation error. 

27 Negative base to non-integer power. Exponentiation error. 

28 LOG or LGT of a non-positive number. 

29 Illegal floating point number. Does not occur as a result of any calculations, but is possible when a 
FORMAT OFF I/O operation fills a REAL variable with something other than a REAL number. 

30 SQR of a negative number. 

31 Division (or MOD) by zero. 

32 String does not represent a valid number. Attempt to use “non-numeric” characters as an 
argument for VAL, data for a READ, or in response to an INPUT statement requesting a number. 

33 Improper argument for NUM or RPT$. Null string not allowed. 

34 Referenced line not an IMAGE statement. A USING clause contains a line identifier, and the line 
referred to is not an IMAGE statement. 

35 Improper image. See IMAGE or the appropriate keyword in the BASIC Language Reference. 

36 Out of data in READ. A READ statement is expecting more data than is available in the referenced 
DATA statements. Check for deleted lines, proper OPTION BASE, proper use of RESTORE, or 
typing errors. 

38 TAB or TABXY not allowed here. The tab functions are not allowed in statements that contain a 
USING clause. TABXY is allowed only in a PRINT statement. 

40 Improper REN, COPYLINES, or MOVELINES command. Line numbers must be whole numbers 
from 1 to 32 766. This may also result from a COPYLINES or MOVELINES statement whose 
destination line numbers lie within the source range. 

41 First line number greater than second line number. Parameters out of order in a statement like 
SAVE, LIST, or DEL. 

43 Matrix must be square. The MAT functions: IDN, INV, and DET require the array to have equal 
numbers of rows and columns. 

44 Result cannot be an operand. Attempt to use a matrix as both result and argument in a MAT TRN 
or matrix multiplication. 

46 Attempting a SAVE when there is no program in memory. 

47 COM declarations are inconsistent or incorrect. Includes such things as mismatched dimensions, 
unspecified dimensions, and blank COM occurring for the first time in a subprogram. 

49 Branch destination not found. A statement such as ON ERROR or ON KEY refers to a line that 
does not exist. Branch destinations must be in the same context as the ON...statement. 
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51 File not currently assigned. Attempting an ON/OFF END statement with an unassigned I/O path 
name. 

52 Improper mass storage unit specifier. The characters used for a msus do not form a valid specifier. 
This could be a missing colon, too many parameters, illegal characters, etc. 

53 Improper file name. File names are limited to 10 characters. Foreign characters are allowed, but 
punctuation is not. 

54 Duplicate file name. The specified file name already exists in directory. It is illegal to have two files 
with the same name on one volume. 

55 Directory overflow. Although there may be room on the media for the file, there is no room in the 
directory for another file name. Discs initialized by BASIC have room for over 100 entries in the 
directory, but other systems may make a directory of a different size. 

56 File name is undefined. The specified file name does not exist in the directory. Check the contents 
of the disc with a CAT command. 

58 Improper file type. Many mass storage operations are limited to certain file types. For example, 
LOAD is limited to PROG files and ASSIGN is limited to ASCII and BDAT files. 

59 End of file or buffer found. For files: No data left when reading a file, or no space left when writing 

a file. For buffers: No data left for an ENTER, or no buffer space left for an OUTPUT. Also, 

WORD-mode TRANSFER terminated with odd number of bytes. 

60 End of record found in random mode. Attempt to ENTER a field that is larger than a defined 
record. 

62 Protect code violation. Failure to specify the protect code of a protected file, or attempting to 
protect a file of the wrong type. 

64 Mass storage media overflow. There is not enough contiguous free space for the specified file size. 
The disc is full. 

65 Incorrect data type. The array used in a graphics operation, such as GLOAD, is the wrong type 
(INTEGER or REAL). 

66 INITIALIZE failed. Too many bad tracks found. The disc is defective, damaged, or dirty. 

67 Illegal mass storage parameter. A mass storage statement contains a parameter that is out of 
range, such as a negative record number or an out of range number of records. 

68 Syntax error occurred during GET. One or more lines in the file could not be stored as valid 
program lines. The offending lines are usually listed on the system printer. Also occurs if the first 
line in the file does not start with a valid line number. 

72 Disc controller not found or bad controller address. The msus contains an improper device 
selector, or no external disc is connected. 

73 Improper device type in mass storage unit specifier. The msus has the correct general form, but 
the characters used for a device type are not recognized. 

76 Incorrect unit number in mass storage unit specifier. The msus contains a unit number that does 
not exist on the specified device. 

77 Attempt to purge an open file. The specified file is assigned to an I/O path name which has not 
been closed. 

78 Invalid mass storage volume label. Usually indicates that the media has not been initialized on a 
compatible system. Could also be a bad disc. 

79 File open on target device. Attempt to copy an entire volume with a file open on the destination 
disc. 



386 


80 Disc changed or not in drive. Either there is no disc in the drive or the drive door was opened 
while a file was assigned. 

81 Mass storage hardware failure. Also occurs when the disc is pinched and not turning. Try reinsert¬ 
ing the disc. 

82 Mass storage unit not present. Hardware problem or an attempt to access a left-hand drive on the 
Model 226. 

83 Write protected. Attempting to write to a write_protected disc. This includes many operations such 
as PURGE, INITIALIZE, CREATE, SAVE, OUTPUT, etc. 

84 Record not found. Usually indicates that the media has not been initialized. 

85 Media not initialized. (Usually not produced by the internal drive.) 

87 Record address error. Usually indicates a problem with the media. 

88 Read data error. The media is physically or magnetically damaged, and the data cannot be read. 

89 Checkread error. An error was detected when reading the data just written. The media is probably 
damaged. 

90 Mass storage system error. Usually a problem with the hardware or the media. 

93 Incorrect volume code in MSUS. The MSUS contains a volume number that does not exist on the 

specified device. 

100 Numeric IMAGE for string item. 

101 String IMAGE for numeric item. 

102 Numeric field specifier is too large. Specifying more than 256 characters in a numeric field. 

103 Item has no corresponding IMAGE. The image specifier has no fields that are used for item 
processing. Specifiers such as * X / are not used to process the data for the item list. Item¬ 
processing specifiers include things like K D B A. 

105 Numeric IMAGE field too small. Not enough characters are specified to represent the number. 

106 IMAGE exponent field too small. Not enough exponent characters are specified to represent the 
number. 

107 IMAGE sign specifier missing. Not enough characters are specified to represent the number. 
Number would fit except for the minus sign. 

117 Too many nested structures. The nesting level is too deep for such structures as FOR, SELECT, 
IF, LOOP, etc. 

118 Too many structures in context. Refers to such structures as FOR/NEXT, IF/THEN/ELSE 
SELECT/CASE, WHILE, etc. 

120 Not allowed while program running. The program must be stopped before you can execute this 
command. 

121 Line not in main program. The run line specified in a LOAD or GET is not in the main context. 

122 Program is not continuable. The program is in the stopped state, not the paused state. CONT is 
allowed only in the paused state. 

126 Quote mark in unquoted string. Quote marks must be used in pairs. 

127 Statements which affect the knob mode are out of order. 

128 Line too long during GET. 

131 Unrecognized non-ASCII keycode. An output to the keyboard contained a CHR$(255) followed 
by an illegal byte. 



387 


132 Keycode buffer overflow. Trying to send too many characters to the keyboard buffer with an 
OUTPUT 2 statement. 

133 DELSUB of non-existent or busy subprogram. 

134 Improper SCRATCH statement. 

135 READIO/WRITEIO to nonexistent memory location. 

136 REAL underflow. The input or result is closer to zero than lO 308 (approximately). 

140 Too many symbols in the program. Symbols are variable names, I/O path names, COM block 
names, subprogram names, and line identifiers. 

141 Variable cannot be allocated. It is already allocated. 

142 Variable not allocated. Attempt to DEALLOCATE a variable that was not allocated. 

143 Reference to missing OPTIONAL parameter. The subprogram is trying to use an optional para¬ 
meter that didn’t have any value passed to it. Use NPAR to check the number of passed 
parameters. 

145 May not build COM at this time. Attempt to add or change COM when a program is running. For 
example, a program does a LOADSUB and the COM in the new subprogram does not match 
existing COM. 

146 Duplicate line label in context. There cannot be two lines with the same line label in one context. 

150 Illegal interface select code or device selector. Value out of range. 

152 Parity error. 

153 Insufficient data for ENTER. A statement terminator was received before the variable list was 
satisfied. 

154 String greater than 32 767 bytes in ENTER. 

155 Improper interface register number. Value out of range or negative. 

156 Illegal expression type in list. For example, trying to ENTER into a constant. 

157 No ENTER terminator found. The variable list has been satisfied, but no statement terminator was 
received in the next 256 characters. The * specifier allows the statement to terminate when the 
last item is satisfied. 

158 Improper image specifier or nesting images more than 8 deep. The characters used for an image 
specifier are improper or in an improper order. 

159 Numeric data not received. When entering characters for a numeric field, an item terminator was 
encountered before any “numeric” characters were received. 

160 Attempt to enter more than 32 767 digits into one number. 

163 Interface not present. The intended interface is not present, set to a different select code, or is 
malfunctioning. 

164 Illegal BYTE/WORD operation. Attempt to ASSIGN with the WORD attribute to a non-word 
device. 

165 Image specifier greater than dimensioned string length. 

167 Interface status error. Exact meaning depends upon the interface type. With HP-IB, this can 
happen when a non-controller operation by the computer is aborted by the bus. 

168 Device timeout occurred and the ON TIMEOUT branch could not be taken. 





388 


170 I/O operation not allowed. The I/O statement has the proper form, but its operation is not defined 
for the specified device. For example, using an HP-IB statement on a non-HP-IB interface or 
directing a LIST to the keyboard. 

171 Illegal I/O addressing sequence. The secondary addressing in a device selector is improper or 
primary address too large for specified device. 

172 Peripheral error. PSTS line is false. If used, this means that the peripheral device is down. If PSTS 
is not being used, this error can be suppressed by using control register 2 of the GPIO. 

173 Active or system controller required. The HP-IB is not active controller and needs to be for the 
specified operation. 

174 Nested I/O prohibited. An I/O statement contains a user-defined function. Both the original 
statement and the function are trying to access the same file or device. 

177 Undefined I/O path name. Attempting to use an I/O path name that is not assigned to a device or 
file. 

178 Trailing punctuation in ENTER. The trailing comma or semicolon that is sometimes used at the 
end of OUTPUT statements is not allowed at the end of ENTER statements. 

301 Cannot do while connected. 

303 Not allowed when trace active. 

304 Too many characters without terminator. 

306 Interface card failure. The datacomm card has failed self-test. 

308 Illegal character in data. Datacomm error. 

310 Not connected. Datacomm error. 

313 USART receive buffer overflow. Overrun error detected. Interface card is unable to keep up with 
incoming data rate. Data has been lost. 

314 Receive buffer overflow. Program is not accepting data fast enough to keep up with incoming data 
rate. Data has been lost. 

315 Missing data transmit clock. A transmit timeout has occurred because a missing data clock 
prevented the card from transmitting. The card has disconnected from the line. 

316 CTS false too long. The interface card was unable to transmit for a predetermined period of time 
because Clear-To-Send was false on a half-duplex line. The card has disconnected from the line. 

317 Lost carrier disconnect. Data Set Ready (DSR) or Data Carrier Detect (if full duplex) went inactive 
for too long. 

318 No activity disconnect. The card has disconnected from the line because no data was transmitted 
or received for a predetermined length of time. 

319 Connection not established. Data Set Ready or Data Carrier Detect (if full duplex) did not become 
active within a predetermined length of time. 

324 Card trace buffer overflow. 

325 Illegal databits/parity combination. Attempting to program 8 bits-per-character and a parity of “1” 
or “0”. 

326 Register address out of range. A control or status register access was attempted to a non-existent 
register. 

327 Register value out of range. Attempting to place an illegal value in a control register. 

328 USART Transmit underrun. 
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330 User-defined LEXICAL ORDER IS table size exceeds array size. 

331 Repeated value in pointer. A MAT REORDER vector has repeated subscripts. This error is not 
always caught. 

332 Non-existent dimension given. Attempt to specify a non-existent dimension in a MAT REORDER 
operation. 

333 Improper subscript in pointer. A MAT REORDER vector specifies a non-existent subscript. 

334 Pointer size is not equal to the number of records. A MAT REORDER vector has a different 
number of elements than the specified dimension of the array. 

335 Pointer is not a vector. Only single-dimension arrays (vectors) can be used as the pointer in a MAT 
REORDER or a MAT SORT statement. 

337 Substring key is out-of-range. The specified substring range of the sort key exceeds the dimen¬ 
sioned length of the elements in the array. 

338 Key subscript out-of-range. Attempt to specify a subscript in a sort key outside the current bounds 
of the array. 

340 Mode table too long. User-defined LEXICAL ORDER IS mode table contains more than 63 
entries. 

341 Improper mode indicator. User-defined LEXICAL ORDER IS table contains an illegal combina¬ 
tion of mode type and mode pointer. 

342 Not a single-dimension integer array. User-defined LEXICAL ORDER IS mode table must be a 
single-dimension array of type INTEGER. 

343 Mode pointer is out of range. User-defined LEXICAL ORDER IS table has a mode pointer greater 
than the existing mode table size. 

344 1 for 2 list empty or too long. A user-defined LEXICAL ORDER IS table contains an entry 
indicating an improper number of 1 for 2 secondaries. 

345 CASE expression type mismatch. The SELECT statement and its CASE statements must refer to 
the same general type, numeric or string. 

346 INDENT parameter out-of-range. The parameters must be in the range: 0 thru eight characters 
less than the screen width. 

347 Structures improperly matched. There is not a corresponding number of structure beginnings and 
endings. Usually means that you forgot a statement such as END IF, NEXT, END SELECT, etc. 

349 CSUB has been modified. A contiguous block of compiled subroutines has been modified since it 
was loaded. A single module that shows as multiple CSUB statements has been altered because 
program lines were inserted or deleted. 

353 Data link failure. 

370-399 Errors in this range are reported if a run-time Pascal error occurs in a CSUB. To determine the 
Pascal error number, subtract 400 from the BASIC error number. Information on the Pascal error 
can be found in the Pascal User’s Manual. 

401 Bad system function argument. An invalid argument was given to a time, date, base conversion, 
or SYSTEMS function. 

403 Copy failed; program modification incomplete. An error occurred during a COPYLINES or 
MOVELINES resulting in an incomplete operation. Some lines may not have been copied or 
moved. A 

427 Priority may not be lowered. 






450 

451 

453 

454 

455 

456 

457 

458 

459 

460 

462 

465 

471 

481 

482 

483 

484 

485 

488 

511 

600 

601 

602 

603 

604 

605 

606 

607 

609 

612 


Volume not found—SRM error. 

Volume labels do not match—SRM error. 

File in use—SRM error. 

Directory formats do not match—SRM error. 

Possibly corrupt file—SRM error. 

Unsupported directory operation—SRM error. 

Passwords not supported—SRM error. 

Unsupported directory format—SRM error. 

Specified file is not a directory—SRM error. 

Directory not empty—SRM error. 

Invalid password—SRM error. 

Invalid rename across volumes—SRM error. 

TRANSFER not supported by the interface. 

File locked oropen exclusively—SRM error. 

Cannot move a directory with a RENAME operation—SRM error. 

System down—SRM error. 

Password not found—SRM error. 

Invalid volume copy—SRM error. 

DMA hardware required. HP 9885 disc drive requires a DMA card oris malfunctioning. 

The result array in a MAT INV must be of type REAL. 

Attribute cannot be modified. The WORD/BYTE mode cannot be changed after assigning the I/O 
path name. 

Improper CONVERT lifetime. When the CONVERT attribute is included in the assignment of an 
I/O path name, the name of a string variable containing the conversion is also specified. The 
conversion string must exist as long as the I/O path name is valid. 

Improper BUFFER lifetime. The variable designated as a buffer during an I/O path name assign¬ 
ment must exist as long as the I/O path name is valid. 

Variable was not declared as a BUFFER. Attempt to assign a variable as a buffer without first 
declaring the variable as a BUFFER. 

Bad source or destination for a TRANSFER statement. Transfers are not allowed to the CRT, 
keyboard, or tape backup on CS80 drives. Buffer to buffer or device to device transfers are not 
allowed. 

BDAT file type required. Only BDAT files can be used in a TRANSFER operation. 

Improper TRANSFER parameters. Conflicting or invalid TRANSFER parameters were specified, 
such as RECORDS without and EOR clause, or DELIM with an outbound TRANSFER. 

Inconsistent attributes. Such as CONVERT or PARITY with FORMAT OFF. 

IVAL or DVAL result too large. Attempt to convert a binary, octal, decimal, or hexadecimal string 
into a value outside the range of the function. 

BUFFER pointers in use. Attempt to change one or more buffer pointers while a TRANSFER is in 
progress. 
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700 Improper plotter specifier. The characters used as a plotter specifier are not recognized. May be 
misspelled or contain illegal characters. 

702 CRT graphics hardware missing. Hardware problem. 

704 Upper bound not greater than lower bound. Applies to P2< = P1 or VIEWPORT upper bound 
and CLIP limits. 

705 VIEWPORT or CLIP beyond hard clip limits. 

708 Device not initialized. 

713 Request not supported by specified device. Trying to equate color CRT characteristics with an 
external device; such as COLOR MAP on a plotter. 

733 GESCAPE opcode not recognized. Only values 1 thru 5 can be used. 

900 Undefined typing aid key. 

901 Typing aid memory overflow. 

902 Must delete entire context. Attempt to delete a SUB or DEF FN statement without deleting its 
entire context. Easiest way to delete is with DELSUB. 

903 No room to renumber. While EDIT mode was renumbering during an insert, all available line 
numbers were used between insert location and end of program. 

904 Null FIND or CHANGE string. 

905 CHANGE would produce a line too long for the system. Maximum line length is two lines on the 
CRT. 

906 SUB or DEF FN not allowed here. Attempt to insert a SUB or DEF FN statement into the middle 
of a context. Subprograms must be appended at the end. 

909 May not replace SUB or DEF FN. Similar to deleting a SUB or DEF FN. 

910 Identifier not found in this context. The keyboard-specified variable does not already exist in the 
program. Variables cannot be created from the keyboard; they must be created by running a 
program. 

911 Improper I/O list. 

920 Numeric constant not allowed. 

921 Numeric identifier not allowed. 

922 Numeric array element not allowed. 

923 Numeric expression not allowed. 

924 Quoted string not allowed. 

925 String identifier not allowed. 

926 String array element not allowed. 

927 Substring not allowed. 

928 String expression not allowed. 

929 I/O path name not allowed. 

930 Numeric array not allowed. 

931 String array not allowed. 

932 Excess keys specified. A sort key was specified following a key which specified the entire record. 
935 Identifier is too long: 15 characters maximum. 
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936 Unrecognized character. Attempt to store a program line containing an improper name or illegal 
character. 

937 Invalid OPTION BASE. Only 0 and 1 are allowed. 

939 OPTIONAL appears twice. A parameter list may have only one OPTIONAL keyword. All para¬ 
meters listed before it are required, all listed after it are optional. 

940 Duplicate formal parameter name. 

942 Invalid I/O path name. The characters after the @ are not a valid name. Names must start with a 
letter. 

943 Invalid function name. The characters after the FN are not a valid name. Names must start with a 
letter. 

946 Dimensions are inconsistent with previous declaration. The references to an array contain a 
different number of subscripts at different places in the program. 

947 Invalid array bounds. Value out of range, or more than 32 767 elements specified. 

948 Multiple assignment prohibited. You cannot assign the same value to multiple variables by stating 
X = y = Z = 0. A separate assignment must be made for each variable. 

949 This symbol not allowed here. This is the general “syntax error” message. The statement you 
typed contains elements that don’t belong together, are in the wrong order, or are misspelled. 

950 Must be a positive integer. 

951 Incomplete statement. This keyword must be followed by other items to make a valid statement. 

961 CASE expression type mismatch. The CASE line contains items that are not the same general 
type, numeric or string. 

962 Programmable only: cannot be executed from the keyboard. 

963 Command only: cannot be stored as a program line. 

977 Statement is too complex. Contains too many operators and functions. Break the expression 

down so that it is performed by two or more program lines. 

980 Too many symbols in this context. Symbols include variable names, I/O path names, COM block 
names, subprogram names, and line identifiers. 

982 Too many subscripts: maximum of six dimensions allowed. 

983 Wrong type or number of parameters. An improper parameter list for a machine-resident func¬ 
tion. 

985 Invalid quoted string. 

987 Invalid line number: must be a whole number 1 thru 32 766. 
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Second Byte of Non-ASCII Key Sequences 

Holding the CTRL key and pressing a non-ASCII key generates a two-character sequence on 
the CRT. The first character is an “inverse-video” K. This table can be used to look up the key 
that corresponds to the second character of the sequence. 



Character 

Value 

Key 

P 

80 

(PAUSE) 

0 


l 

R 

82 

( RUN ) 

S 

83 

( step) 

T 

84 

(SHIFT)-) J ) 

U 

85 

(CAPS LOCK) 

V 

86 

U_J 

W 

87 

( SHIFT) -( t ) 

X 

88 

( EXECUTE ) 

Y 

89 

Roman Mode 

Z 


i 

c 

91 

( CLR TAB ) 

\ 

92 

LrJ 

] 

93 

( SET TAB ) 

* 

94 

(_i_) 

- 

95 

fsHiFfl-rr - ) 

1 

a 

97 

( k ™ ) 

b 

98 

( hi) 

c 

99 

( hi) 

d 

100 

( k 13 ) 

e 

101 

( h<) 

f 

102 

( k 15 ) 

4 

103 

( k ™ ) 

h 

104 

( to ) 

i 

105 

( hi) 

J 

106 

( hi) 

k 

107 

( to ) 

l 

108 

( hi) 

m 

109 

( te) 

n 

110 

( hs) 

0 

111 

( SHIFT) -system( f\ ) 2 

p 

112 

( SHIFT ]-system! fl ) 2 


113 

( SHIFT ] -system! fZ ) 2 

r 

114 

( SHIFT)-system! M ) 2 

5 

115 

f SHIFT) -userf /I ) 2 

t 

116 

( SHIFT) -userf tl ) 2 

U 

117 

(SHIFT)-userf fZ V 

b 

118 

( SHIFT l-userf/Tl 2 

w 

119 

(SHIFT)-userf fS ) 2 

X 

120 

(SHIFT)-userf /6 ) 2 

Y 

121 

( SHIFT )-usernn 2 

z 

122 

( SHIFT)-userf fZ ) 2 

> 

123 

(System) 

1 

124 

( Menu ) 


125 

fUseD 

~ 

126 

f SHIFT)-( Menu ) 

l 

$ 



1 These characters cannot be generated by pressing the CTRL key and a non-ASCII key. If one of these characters follows CHR$(255) in an 
output to the keyboard, an error is reported (E r ro r 131 Bad non-al phartume ric kevcode*). 

2 System and user refer to the softkey menu which is currently active. 
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US ASCII Character Codes 


EQUIVALENT FORMS 


Char. 

Dec 

Binary 

Oct 

Hex 


NUL 

0 

00000000 

000 

00 


SOH 

1 

00000001 

001 

01 

GTL 

STX 

2 

00000010 

002 

02 


ETX 

3 

00000011 

003 

03 


EOT 

4 

00000100 

004 

04 

SDC 

ENQ 

5 

00000101 

005 

05 

PPC 

ACK 

6 

00000110 

006 

06 


BEL 

7 

00000111 

007 

07 


BS 

8 

00001000 

010 

08 

GET 

HT 

9 

00001001 

011 

09 

TCT 

LF 

10 

00001010 

012 

0A 


VT 

11 

00001011 

013 

OB 


FF 

12 

00001100 

014 

OC 


CR 

13 

00001101 

015 

OD 
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Manual Comment Sheet Instruction 

If you have any comments or questions regarding this manual, write them on the enclosed comment 
sheets and place them in the mail. Include page numbers with your comments wherever possible. 

If there is a revision number, (found on the Printing History page), include it on the comment sheet. 
Also include a return address so that we can respond as soon as possible. 

The sheets are designed to be folded into thirds along the dotted lines and taped closed. Do not use 
staples. 

Thank you for your time and interest. 
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